DataHub Scripting

Version 10.0

May 15, 2024

An implementation of the Gamma scripting language for use in Cogent DataHub software.


Table of Contents
1. Introduction
2. What's Different About DataHub Scripting?
2.1. Scripts and their Environment
2.1.1. Dynamic Environment
2.1.2. Event Driven
2.1.3. Object Oriented
2.2. Symbols, Variables, and Evaluation
2.2.1. Symbols and Variables
2.2.2. The Read/Evaluate Cycle
2.3. Access to DataHub Points
2.3.1. Point Names
2.3.2. Point Values
2.3.3. Point Timestamps and Qualities
2.4. ODBC and Windows Scripting
2.4.1. DataHub ODBC (Open Database Connectivity) Scripting
2.4.2. DataHub Windows Scripting
3. Getting Started
3.1. How to Run a Script
3.2. The Script Editor
3.3. The Script Log
3.4. The Script Application Manager
4. Writing Scripts
4.1. Creating a Script
4.2. Hello World
4.3. Accessing Data
4.4. Modifying Data
4.5. Making a Window
4.6. Encrypting a Script
4.7. Scripting Tips
4.7.1. Copying a complete tutorial
4.7.2. Setting up a scripting environment
4.7.3. The Require folder
5. The Application class
5.1. Class Definition
5.2. Construction and Destruction
5.3. Handling Events
5.4. Timers
5.5. Menus
6. Example Scripts
AutoCalculation.g — automatically calculates formulas based on data points.
SimpleAverage.g — computes average point values over a period of time.
LogFile.g — logs data to a text file when a point changes value.
ReadCSV.g — reads a CSV file and writes the points and values to the DataHub instance.
WriteCSV.g — writes data to CSV files.
XMLReader.g — reads an XML file from a URL.
ParseExcel.g — parses data from an Excel spreadsheet.
LinearXform.g — performs linear transformation functions on points.
MakeArray.g — creates an array point from individual points.
BreakArray.g — breaks an array point into individual points.
IntToBit.g — converts an integer data point into a set of single-bit points.
BitsToInt.g — converts a set of boolean data points into an integer point.
MaskedBridge.g — copies a data point, applying a mask and shift operation.
ConnectionTrack.g — changes a point when a connection is made or broken.
QualityTrack.g — writes the quality of a point as the value of another point.
TagMonitor.g — monitors DataHub points for changes in quality or failure to change value.
TimedUpdate.g — periodically updates the timestamp on a set of DataHub points without changing their values.
FixQuality.g — changes point quality for OPC clients that treat bad quality as a disconnection.
OPCItemLoader.g — reads a list of OPC DA tags from a CSV file and configures DataHub points for them.
OPCReconnect.g — disconnects and reconnects an OPC DA server.
OPCReload.g — requests a reload of OPC DA server data with no disconnect.
7. Built-in Classes
DH_Domain — the structure of a DataHub domain.
DH_Item — the structure of a DataHub point.
8. Special Gamma Functions for DataHub Scripting
_ — looks up a translation text.
add_menu_action — adds a menu action.
allow_self_reference — permits changes to be written back to the point of origin.
datahub_command — sends commands to the DataHub program.
datahub_domaininfo — gives information about data domains.
datahub_domains — creates a list of all domains.
datahub_log — writes a string to the Event Log window.
datahub_points — shows the points in a data domain.
datahub_read — creates a list of all points for a domain.
datahub_write — assigns a value to a DataHub point.
edit_file — opens a file in the Script Editor.
flush_log_file — writes buffered text of Script Log output to the file.
freeze_writes — controls when writes are sent to the DataHub engine.
get_point_queue_count — counts the number of DataHub points queued for the Gamma engine.
get_point_queue_depth — gets the depth of the DataHub instance's per-point queue for the Gamma engine.
get_tray_menu — returns a pointer to the tray menu.
on_change — evaluates an expression when a variable changes value or quality.
remove_change — removes an on_change function.
remove_menu_action — removes a menu action.
set_log_file — sets the file and open mode for writing Script Log output.
set_log_size — sets the maximum log file size for Script Log output.
set_point_flush_flags — determines which data types are not buffered.
set_point_queue_depth — sets the depth of the DataHub instance's per-point queue for Gamma.
show_log — displays the Script Log.
symcmp — compares symbols to see if they are equal.
9. Methods and Functions from Application.g
AddCustomMenuItem — a convenience method for creating a menu item.
AddCustomSubMenu — a convenience method for adding a menu.
AddMenuItem — adds a menu item and attaches code to it.
AddPermanentMenuItem — should not be used.
AddStartMenuItem — should not be used.
AddStopMenuItem — creates a menu item that destroys the running application.
AddSubMenu — creates a submenu on a parent menu.
ApplicationMultiple — allows creation of multiple instances of the class.
ApplicationSingleton — allows creation of only one instance of the class.
CreateSystemMenu — adds a submenu to the system tray menu.
droptimer — for internal use only.
OnChange — attaches an event handler to a point change event.
RemoveAllChanges — removes event handlers from all point change events.
RemoveAllEventHandlers — removes all point change events and all timers.
RemoveAllMenus — removes all script menus, submenus, and menu actions.
RemoveAllTimers — cancels all timers.
RemoveChange — removes an event handler from a point change event.
RemoveSystemMenu — for internal use only.
RemoveTimer — cancels a timer.
TimerAfter — attaches an event handler to an "after" timer.
TimerAt — attaches an event handler to an "at" timer.
TimerEvery — attaches an event handler to an "every" timer.
10. Time Conversion Functions from Time.g
GetCurrentWindowsTime — returns the current clock time in Windows time format.
PointGetUnixTime — gets the Unix time stamp from a point.
PointGetWindowsTime — gets the Windows time stamp from a point.
PointMetadata — queries a point for its metadata structure.
UnixLocalToUTC — converts from local Unix time to UTC.
UnixTimeToWindowsTime — converts from Unix time to Windows time.
UnixUTCToLocal — converts from UTC Unix time to local time.
WindowsLocalToUTC — converts from local Windows time to UTC.
WindowsTimeToUnixTime — converts from Windows time to Unix time.
WindowsUTCToLocal — converts from UTC Windows time to local time.
11. Regular Expression Methods from RegexSupport.g
Compile — compiles a regular expression to a form that is more efficient to evaluate.
CompileSubst — compiles a substitution pattern.
CompileSubstEx — an alternate interface to CompileSubst.
Config — queries the PCRE library for compiled-in options.
Exec — applies a regular expression match to a subject string.
pcrs_job.Exec — applies a compiled pattern substitution to a subject string.
GetStringNumber — retrieves the index number of named substrings.
Match — a convenience function that combines calls to Compile, Study, and Exec.
Study — helpful for speeding up repeated applications of a regular expression.
Subst — applies a substitution pattern to a string of a given length.
12. Calling OPC UA Methods from DataHub Scripts
13. Quality Name Function from Quality.g
GetQualityName — converts the quality value of a point to a text string.
14. Classes from HistorianSupport.g
Historian — encapsulates the Historian facility in the DataHub program.
HistoryBuffer — a set of HistoryValues returned from a Historian query.
HistoryValue — a single value from the Historian, consisting of value, x-axis and quality.
HistTest.g — an example script that demonstrates how to access Historian data.
15. Modbus Commands Methods from ModbusSupport.g
apply — applies all scripted changes.
addPoint — configures a Modbus point.
addRange — configures a range of Modbus points.
cancel — cancels all scripted changes.
createSlave — creates a slave connection.
deletePoint — deletes point connections.
deleteSlave — deletes a slave connection.
enableMaster — enables and disables Modbus master functionality.
enableSlave — enables and disables Modbus slave connections.
reloadSettings — loads all Modbus configuration.
slaveExists — checks for the existence of a slave connection.
1. Basic Troubleshooting
2. License Copyright Information