Cogent DataHub Documentation

Copyright © Skkynet Cloud Systems, Inc. and its subsidiaries and licensors. All rights reserved.

Skkynet, DataHub, Cogent DataHub, the Skkynet and DataHub logos are either registered trademarks or trademarks used under license by the Skkynet group of companies (“Skkynet”) in the USA and elsewhere. All other trademarks, service marks, trade names, product names and logos are the property of their respective owners. For terms and conditions of use and full intellectual property notices, please refer to the Legal Notices on the Skkynet website: https://skkynet.com/legal/.

May 15, 2024


Table of Contents
Cogent DataHub software
1. Installation
1.1. System Requirements and Installation
1.2. Installing Licenses
1.3. Installing as a Service
1.4. Performing a Silent (Unattended) Install
1.5. Upgrading to a new version
1.6. Installing over previous versions
1.7. Downgrading to a previous version
1.8. Configuration Files
1.9. Backing Up or Moving a DataHub Installation
1.10. Known Issues
1.11. FAQ
2. Getting Started
2.1. Running the DataHub Program
2.2. Test with simulated data
2.3. Connect to an OPC DA server
2.4. Connect from an OPC DA client
2.5. Test MQTT
2.6. Connecting to InfluxDB
2.7. Custom Connections
2.8. Performance Limitations
2.9. Troubleshooting
2.9.1. Reporting Problems
2.9.2. Tools
3. Properties Window
3.1. For All Options
3.2. General
3.3. OPC UA
3.4. OPC DA
3.5. OPC A&E
3.6. Tunnel/Mirror
3.7. Bridging
3.8. Redundancy
3.9. Database
3.10. Web Server
3.11. DataHub WebView
3.12. MQTT Client
3.12.1. Make the Connection
3.12.2. Exchange Data
3.12.3. Pre-Configured Connections
3.12.3.1. Azure IoT Hub
3.12.3.2. Google IoT
3.12.3.3. AWS IoT Core
3.12.3.4. Sparkplug
3.13. MQTT Broker
3.14. Modbus
3.15. External Historian
3.15.1. General Configuration
3.15.2. Connection Configuration
3.15.3. Supported Historians
3.15.3.1. Amazon Kinesis
3.15.3.2. AVEVA Historian
3.15.3.3. AVEVA Insight
3.15.3.4. InfluxDB V1
3.15.3.5. InfluxDB V2
3.15.3.6. OSIsoft PI
3.15.3.7. REST Client
3.15.3.8. Tunnel (Pull)
3.15.3.9. Tunnel (Push)
3.16. Notification
3.17. InfluxDB
3.17.1. Configuration
3.17.2. Grafana
3.17.3. Chronograf
3.17.4. Advanced Topics
3.18. Email/SMS
3.19. Camera
3.20. System Monitor
3.21. DDE
3.22. Historian
3.23. Quick Trend
3.24. Remote Config
3.25. Scripting
3.26. Security
3.27. Licenses
4. Other Windows and Programs
4.1. Data Browser
4.2. Connection Viewer
4.3. Event Log
4.4. Script Editor
4.5. Script Log
4.6. DataSim - a data simulation program
4.7. DataPid - a PID loop data simulation program
4.8. Remote Config
4.8.1. Preparation
4.8.2. Configuring a Local DataHub Instance
4.8.3. Configuring a Remote DataHub Instance
4.9. Service Manager
5. Tunnelling OPC DA
5.1. Introduction
5.2. Configuring the DataHub instance for the server
5.3. Configuring the DataHub instance for the client
5.4. Testing the connection
5.5. Combinations
5.5.1. Multiple connections
5.5.2. Bridging
5.5.3. Partial data sets
6. Tunnelling Scenarios
6.1. Tunnelling - Firewalls Open
6.2. Tunnelling - One Firewall Closed
6.3. Tunnelling - Both Firewalls Closed, with DMZ
6.4. TCP Ports and DataHub Tunnelling
7. OPC UA Connections
7.1. Introduction
7.2. Acting as an OPC UA Client
7.3. Acting as an OPC UA Server
7.4. Endpoints and Discovery
7.5. Security
7.6. Certificates
7.7. OPC UA to DA Conversions
7.8. OPC A&C to OPC A&E Conversions
7.9. Object Model
7.10. OPC UA Methods
7.11. Restricting Connections
7.12. OPC UA Test Client and Server
7.12.1. Using a Test Client
7.12.2. Using a Test Server
7.13. Troubleshooting
7.13.1. Endpoint URLs
7.13.2. Error Messages
7.13.3. Expired LDS certificate
8. Bridging
8.1. Introduction
8.2. Configuring Bridges
8.2.1. Point-to-point configuration
8.2.2. Making transformations
8.3. Creating New Points
8.4. Configuring Many Bridges
8.5. Bridging Scenarios
8.5.1. Bridging Local Servers
8.5.2. Bridging Remote Servers
8.5.3. Creating Data Sets
8.5.4. Bridging to Excel
8.5.5. Bridging and Tunnelling
9. Using Redundancy
9.1. Typical Scenarios
9.2. Configure the Switch
9.3. Troubleshooting
9.4. Multiple Redundant Pairs
9.5. Warm Standby
9.6. Special Cases Q&A
10. Write to a Database
10.1. Introduction
10.2. Quick Start
10.3. Configuring the Queue, Store and Forward
10.4. Setting up the DSN (Data Source Name)
10.5. Configuring a Database Table
10.6. Key Columns
10.7. Assigning a Trigger
10.8. Setting Trigger Conditions
10.9. Configured Actions
11. Query a Database
11.1. Introduction
11.2. Quick Start
11.3. Setting up the DSN (Data Source Name)
11.4. Configuring a Database Query
11.5. Assigning a Trigger
11.6. Setting Trigger Conditions
11.7. Configured Actions
12. Using the Web Server
12.1. Introduction
12.2. Configuring the DataHub Web Server
12.3. Using ASP to Query a Database and Display Results
12.4. Connecting Browser Applications
12.4.1. ASP Document Requests
12.4.2. WebSocket Connections
12.5. ASP File Locations
13. Using MQTT
13.1. Connecting MQTT Clients with the DataHub MQTT Broker
13.2. Making MQTT Client Connections
13.3. MQTT Advanced Parser Tutorial
13.3.1. Example - Part One
13.3.2. Example - Part Two
13.3.3. Example - Part Three
13.4. MQTT Advanced Parser Reference
13.4.1. Overview
13.4.2. Receive Format
13.4.2.1. Testing a Receive Format
13.4.2.2. Script Execution
13.4.2.3. Topic Name Manipulation
13.4.2.4. Initialization Script
13.4.2.5. Parser Script
13.4.3. Common Formulas
13.4.4. Publish Formats
13.4.5. Exporting, Importing and Duplicating Parsers
13.5. Broker $SYS Topics
14. Using the External Historian
14.1. Typical Scenarios
14.2. Connecting
14.3. Store and Forward
14.4. Tunnel (Push)
14.5. Receiving Side
14.6. Tunnel (Pull)
14.7. Using a DMZ
15. Security
15.1. How to Configure
15.2. SSL Encryption
15.2.1. SSL Certificates and Firewalls
15.2.2. Editing OpenSSL ciphers and options
15.2.3. Modifying SSL Security Levels
15.3. User Authentication
15.4. Authorization and User Permissions
15.5. Permissions for the DataHub Command Set
15.6. Passwords
15.7. Tunnelling Security - Best Practices
16. Making Notifications
16.1. Configure a Notifier
16.2. Define a Template
16.3. Bind a Variable
16.4. Twilio
16.5. OPC A&E
16.6. Multiple Variables
16.7. Multiple States
16.8. A&E Event Settings
16.9. Regular Expressions
17. Email and SMS
17.1. Introduction
17.2. Configuring the Mail Server
17.3. Sending a Test Message
17.4. Defining the Email Message
17.5. Assigning a Trigger
17.6. Setting Trigger Conditions
17.7. Configured Actions
17.8. Sending SMS Text Messages
17.9. HTML Message Examples
17.9.1. An HTML Message with Embedded Data Points
17.9.2. An HTML Message with a Table Created in Code
17.10. Dynamically Changing Email Subjects and Recipients
18. System Monitor
18.1. Introduction
18.2. Configuring the System Monitor
18.3. Monitoring Systems Across a Network
19. Excel Connections
19.1. Getting Data into Excel
19.1.1. Method 1 - Drag and Drop using DDEAdvise
19.1.2. Method 2 - Excel Macros using DDERequest
19.1.2.1. Create a macro
19.1.2.2. Add a Control Button
19.1.2.3. Receive the data
19.2. Getting Data out of Excel
19.2.1. Method 1 - Configuring DDEAdvise loops in the DataHub instance
19.2.2. Method 2 - Writing Excel macros that use the DDEPoke command
19.2.2.1. Create a macro
19.2.2.2. Add a Control Button
19.2.2.3. Send the data
19.2.2.4. Additional Pointers
19.3. Networking Excel
19.4. Working with Ranges
19.4.1. Getting a Range out of Excel
19.4.2. Getting a Range into Excel
19.4.3. Sample Excel Macros for Arrays
19.5. Basic Trouble-Shooting for Excel Connections
20. DataHub Scripting
20.1. Tools
20.2. DataHub ODBC (Open Database Connectivity) Scripting
20.3. DataHub Windows Scripting
21. Working With Data
21.1. Data Points
21.1.1. Creating New Points
21.1.2. Deleting Points
21.1.3. Viewing Data Points
21.1.4. Point Size Limits
21.1.5. Data Types
21.1.6. Coercing a Number to a DATE Type
21.2. Data Communication Concepts
21.2.1. Send and Receive Data
21.2.2. Client - Server
21.2.3. Synchronous and Asynchronous Communication
21.3. Data Exchange Protocols
21.3.1. OPC Protocol
21.3.2. DDE Protocol
21.3.3. Tunnelling/Mirroring
21.3.4. The DataHub APIs
21.4. Data Organization
21.4.1. Data Domains
21.4.2. Assemblies, Subassemblies, Attributes, and Properties
21.4.3. Attributes and Types
21.4.4. Example 1: Attributes and Types
21.4.5. Example 2: Private Attributes
22. Optimizing Data Throughput
22.1. Binary Mode Tunnel/Mirror (TCP) Connections
22.2. Tunnel/Mirror (TCP) Heartbeat and Timeout
22.3. Old Value Queuing
22.4. Un-Buffered Delivery
22.5. Screen Output
22.6. CPU Saturation
22.7. How to Optimize
22.7.1. Tunnel/Mirror (TCP) connections
22.7.2. DataHub C++ API
22.7.3. Gamma scripts
23. Using DataHub Commands
23.1. Command Syntax
23.2. Return Syntax
23.3. Sending Commands by TCP
Cogent DataHub Command Set
acksuccess — tells the DataHub instance to return success messages.
add — adds a value to a point.
alias — creates an alias point for an existing point.
alive — tells a DataHub instance that the client is running.
append — appends a string to the value of a point.
assembly — creates an assembly.
attribute — creates an attribute.
auth — requests authentication for a client.
authreload — is new, not yet documented.
auto_create_domains — automatically adds domains requested by clients.
auto_timestamp — adds timestamps to unstamped changes.
bridge — creates a bridge between two points.
bridge_remove — deletes a bridge.
bridge_remove_pattern — deletes all bridges that match a pattern.
bridge_transform — modifies an existing bridge.
cforce — creates a point and forces a value to be written to it.
cread — creates and reads a point.
create — creates a new point.
create_domain — creates a new domain.
creport — creates a point and requests notification of changes.
cset — creates a point and assigns it a value.
cwrite — creates a point and writes information to it.
DDEAdvise — sets up the item for a DDEAdvise connection.
DDEConnect — makes a connection to a DDE service and topic.
DDEDisconnect — disconnects and discards a DDE connection.
DDEExcelUnicode — accepts Unicode characters in strings in Excel.
DDEInit — initializes the a DataHub instance to act as a DDE server.
DDEService — assigns a DDE service name.
DDEUnadvise — removes an item from a DDE connection.
DDEUnadvisePattern — removes multiple items from a DDE connection.
DDEUnadvisePoint — removes an item from a DDE connection, by its point name.
debug — sets the debug level.
defaultprop — sets a default type for a property.
delete — deletes a point—use with caution.
div — does division on the value of a point.
domain — identifies the client domain name.
domain_bridge — configures a redundancy set.
domain_bridge_enable — enables or disables the Redundancy feature.
domain_bridge_prefer — specifies a preferred source for a Redundancy connection.
domain_bridge_refresh — refreshes a Redundancy connection.
domain_bridge_remove — removes a Redundancy connection.
domains — lists all domains in a DataHub instance.
dump — writes the entire content of a DataHub instance to a file.
enable_bridging — enables or disables bridging capabilities.
enable_dde_client — enables or disables DDE client capabilities.
enable_dde_server — enables or disables DDE server capabilities.
enable_domain_bridging — enables or disables domain bridging capabilities.
enable_opc_client — enables or disables OPC client capabilities.
enable_opc_server — enables or disables OPC server capabilities.
enable_scripting — enables or disables scripting capabilities
error — sends an error with an error string.
execute_plugin — executes a plugin. (experimental)
exit — shuts down a DataHub instance.
ExternalHistorianAddPoint — adds a data point for this historian connection.
ExternalHistorianApplyEdit — applies edits made to the temporary copy of the configuration.
ExternalHistorianBeginEdit — creates a temporary copy of the configuration for editing.
ExternalHistorianCancelEdit — deletes the temporary configuration and all edits made to it.
ExternalHistorianEnable — enables or disables external historian connections.
ExternalHistorianGet — gets the value of a historian configuration option.
ExternalHistorianRemovePoint — removes a data point from a historian connection.
ExternalHistorianSet — sets the value of a historian configuration option.
force — forces a write to a point.
format — is an efficiency enhancement for Linux.
get_client_stats — provides statistics for all clients.
heartbeat — establishes a heartbeat message.
HistorianAdd — adds a point to a Historian group.
HistorianFlags — is new, not yet documented.
HistorianRemove — removes points.
HistorianSaveConfig — saves the configuration of the Historian.
HistorianSetConfiguring — sets the Historian status to "Configuring".
HistoryGroupAdd — adds a new history group.
HistoryGroupAddPoint — adds a point to a Historian group.
HistoryGroupDeadband — sets a deadband for a Historian group.
HistoryGroupDefault — sets a default group.
HistoryGroupFileTimes — sets a frequency for changing history files.
HistoryGroupFlushTimes — specifies how frequently to flush history data to disk.
HistoryGroupRemove — removes a group and all of its histories.
HistoryGroupStorageTimes — specifies how long to keep data in a history.
ignore — ignores a given point.
ignore_old_data — ignores changes with an old timestamp.
include — includes a file in with configuration files.
instance — creates an instance of a data organization model.
load_config_files — loads configuration files.
load_plugin — loads a specified plugin. (experimental)
load_scripts — loads scripts.
lock — locks and unlocks points.
log_file — sets up a log file.
log_file_max — sets a size limit for log files.
log_to_file — starts or stops logging to a file.
mirror_master — sets up a mirroring master.
mirror_master_2 — sets up a secure mirroring master.
ModbusApplySettings — applies all scripted changes.
ModbusCancelSettings — cancels all scripted changes.
ModbusCreateSlave — creates a slave connection.
ModbusDeleteSlave — deletes a slave connection.
ModbusEnableMaster — enables and disables Modbus master functionality.
ModbusEnableSlave — enables and disables Modbus slave connections.
ModbusQuerySlave — checks for the existence of a slave connection.
ModbusReloadSettings — loads all Modbus configuration.
ModbusSlaveAddPoint — configures a Modbus point.
ModbusSlaveAddRange — configures a range of Modbus points.
ModbusSlaveDeletePoint — deletes point connections.
mult — multiplies the value of a point.
OPCActivate — activates or deactivates an OPC group.
OPCAddItem2 — adds OPC items to a connection.
OPCAEAttach — creates an OPC A&E connection.
OPCAEDetach — deletes an OPC A&E connection.
OPCAEEnable — enables an OPC A&E connection.
OPCAEEnableClient — enables OPC A&E client behavior.
OPCAEEnableServer — enables OPC A&E server behavior.
OPCAEFilter — selects alarms and events by filtering criteria.
OPCAEServerInit — configures the OPC A&E server.
OPCApply — applies changes to an outgoing connection.
OPCAttach2 — sets up an OPC connection.
OPCConnect — connects or disconnects from the OPC server.
OPCDetach — removes an outgoing OPC connection.
OPCEnable — enables or disables outgoing OPC connections.
OPCEnableClient — enables or disables all OPC clients.
OPCEnableServer — enables or disables DataHub OPC server behavior.
OPCMinimumSecurity — overrides DCOM security settings.
OPCModify — modifies an existing OPC connection.
OPCQueryConnection — provides information related to an OPC server connection.
OPCQueryConnections — lists OPC server connections.
OPCQueryPoint — provides data about an OPC point.
OPCQueryPointPattern — provides data about multiple OPC points.
OPCQueryPoints — provides a list of explicitly configured OPC tags in a connection.
OPCRefresh — sends a Refresh2 command to the OPC server.
OPCReload — reloads the data set from an OPC server.
OPCRemoveItem — removes an item based on its DataHub point name.
private_attribute — creates a private attribute.
property — creates a property for an assembly.
quality — assigns a quality to a point.
read — reads a complete point definition.
report — requests notification of changes to a data point.
report_domain — registers points and requests information on a whole domain.
report_errors — controls the reporting of errors.
request_initial_data — gets current data when client connection is made.
save_config — forces a DataHub instance to save its configuration.
secure — adjusts the security level of a point.
set — sets the value of a point.
set_access — is new, not yet documented.
set_authoritative — sets the type of a point.
set_canonical — sets the type of a point.
show_data — displays the Data Browser.
show_debug_messages — show or hide debugging messages in the Data Browser.
show_event_log — displays the Event Log.
show_icon — displays the system tray icon.
show_properties — displays the Properties window.
show_script_log — displays the Script Log.
subassembly — creates a subassembly.
success — sets up a success message.
tcp_service — sets a TCP service name or port number for incoming slave connections.
timeout — suspends data flow.
transmit_insignificant — permits transmission of insignificant changes.
TunnelDelete — deletes specified tunnel/mirror Slave connections.
TunnelEnable — enables specified tunnel/mirror Slave connections.
TunnelEnablePlain — enables plain-text tunnel/mirror Master connections.
TunnelEnableSlave — enables all tunnel/mirror Slave connections.
TunnelEnableSSL — enables SSL tunnel/mirror Master connections.
TunnelPlainPort — specifies the port for incoming plain-text tunnels.
TunnelSaveConfig — saves the tunnel configuration.
TunnelSlaveStatus — provides status information on tunnel/mirror Slave connections.
TunnelSSLCert — specifies the certificate for incoming SSL-enabled tunnels.
TunnelSSLPort — specifies the port for incoming SSL-enabled tunnels.
type — creates a type.
UAApplyEdit — applies edits to OPC UA configuration.
UABeginEdit — creates a temporary copy of the OPC UA configuration for editing.
UACancelEdit — cancels edits to the OPC UA configuration.
UAEnable — enables or disables an individual OPC UA client connection.
UAEnableClient — enables or disables OPC UA client functionality.
UAEnableServer — enables or disables OPC UA server functionality.
unload_plugin — unloads a plugin. (experimental)
unreport — allows a client to stop receiving data value changes to a point.
unreport_domain — allows a client to stop receiving data value changes in a whole domain.
version — returns the current version number.
write — writes information to a point.
Obsolete and Unused Commands
asyncsocket — sets up asynchronous communication on a socket.
authgroup — is deprecated.
authuser — is deprecated.
bandwidth_reduce — is for internal use only.
deleted — checks if a point has been deleted.
drop_license — is for internal use only.
echo — is for internal use.
enable_connect_server — is deprecated.
EnableDDEServer — is for internal use only.
exception_buffer — is deprecated.
failed_license — is for internal use only.
flush — flushes output to a terminal (Linux).
flush_log — is deprecated.
master_host — is deprecated in favor of mirror_master.
master_service — is deprecated in favor of mirror_master.
on_change — is for internal use only.
OPCAddItem — is deprecated in favor of OPCAddItem2.
OPCAttach — is deprecated in favor of OPCAttach2.
OPCInit — is deprecated.
point — is used internally.
qnx_name_attach — does nothing.
qnx_receiver — does nothing.
readid — should not be used.
register_datahub — replaced by report_domain.
report_all — replaced by report_domain.
report_datahubs — does nothing.
request — replaced by report_domain.
run — does nothing.
script_register — is for internal use only.
script_symbol — is for internal use only.
slave — is for internal use only.
sync — is for internal use only.
taskdied — is for internal use.
taskstarted — is for internal use.
using_license — is for internal use only.
warn_of_license_expiry — is deprecated.
Appendices
1. Command Line Options
2. Excel Macro Library
2.1. Configure Excel to receive data from the DataHub instance (using DDEAdvise)
2.2. Write data from Excel - User initiated (using DDEPoke)
2.3. Write data from Excel - Automatically on value change (using DDEPoke)
2.4. Other Useful Macros
3. Running as a Windows Service (Specified User)
4. Windows Services File for Tunnel/Mirror
5. DataHub Registry Entries
6. OPC Overview
7. DDE Overview
8. ODBC Database Concepts
9. Error Messages
9.1. Windows Error Numbers
9.2. Windows TCP Error Numbers
9.3. Windows DDE Error Numbers
10. Third-Party Source Licenses
11. Media Source Licenses
12. GNU General Public License
13. GNU Lesser General Public License
Cogent DataHub service for Azure
1. Overview
2. Creating the Azure Resource
3. Accessing Your DataHub Service
3.1. Connecting Test Data
3.2. Using Remote Config
3.3. Connecting Process Data
3.4. Activating Features
4. Usage Monitoring
Cogent DataHub Applications
1. Web Application Manager
1.1. Getting Started
1.2. Launching Applications
1.3. Create a Shortcut
2. Remote Config
2.1. Getting Started
2.2. Menu Options
2.3. Monitoring Tools
2.4. Importing Configuration
2.4.1. Opening the Configuration Dialog
2.4.2. Configuring
2.4.3. Available Properties
2.5. Differences between Remote Config and the native DataHub Properties windows
2.6. Software Updates
2.7. Restarting the DataHub instance
3. DHTP - The DataHub Transfer Protocol
Vine Add-in for Microsoft Excel
1. User's Guide
1.1. Getting Started
1.1.1. Overview
1.1.2. Installation
1.1.3. Demo Workbook
1.1.4. Video
1.2. Making a Connection
1.3. Adding Data Points
1.4. Working with Ranges
1.4.1. Demo
1.4.2. Rotate or Cycle
1.5. Troubleshooting
2. Reference
2.1. Connection
2.2. Data Points
2.3. Log
DataHub WebView HMI
1. Introduction
1.1. Run Locally
1.2. Web Launch
1.3. Advanced Launch Options
1.4. DataHub Configuration
1.5. DataHub Security
2. Working With the WebView Application
2.1. Quick Start
2.1.1. Start the WebView Application
2.1.2. Add and Modify a Control
2.1.3. Bind a Control to a Data Point
2.1.4. Save and View a Page
2.1.5. Add a Symbol
2.1.6. Bind a Control to another Control
2.1.7. Set Symbol States
2.2. User Access
2.2.1. Configure User Permissions
2.3. Pages
2.3.1. Create, Open, Save, and Delete Pages
2.3.2. Page Size
2.3.3. The Grid
2.3.4. View and Zoom
2.3.5. Design and Run Modes
2.4. Controls
2.4.1. Add, Copy, Resize, and Move Controls
2.4.2. Grouping Controls
2.4.3. Control Properties
2.4.4. Common Properties
2.4.5. Format Strings
2.4.6. Controls Listed by Category
2.5. Property Binding
2.5.1. DataHub Point Binding
2.5.2. Point Attribute Selection
2.5.3. Simple Binding - Property Picker
2.5.4. Simple Binding - Copy and Paste
2.6. Managing Files
2.6.1. Browsing the Server
2.6.2. File Locations
2.6.3. Editing WebView XML Files
3. WebView Scripting
4. Dynamic Binding
4.1. Dynamic Point Binding
4.1.1. Combo Box control
4.1.2. List Box control
4.2. Dynamic Control and Symbol Binding
4.2.1. Control Binding
4.2.2. Symbol Binding
4.3. Creating a Template Page
5. Customizing the WebView Application
5.1. Simple Branding
5.2. Initialization Parameters
5.2.1. Specifying Parameters
5.2.2. Parameter List
5.3. Adding Controls
6. WebView Controls
Advanced Check Box — toggles between two states, each with advanced properties.
Alarm List — a table that displays alarms and events.
Boolean Converter — a program block that selects between two states.
Calendar — displays a calendar.
Circular Gauge 1 — simple circular gauge.
Circular Gauge 2 — circular gauge with varying value ranges and an indicator light.
Color Selector — a palette used to store specific colors and to access application theme colors.
Color Selector — a program block that uses ARGB values to produce a color.
ComboBox — a simple dropdown list used for item selection.
Comparator — a program block that compares two values and outputs the results.
Condition Selector — a program block used to select among five different states.
Control Panel — supports Run mode option changes.
Date Picker — allows a user to select a date.
Filtered Data Table — row/column results from a database query.
Hi/Low Indicator — changes color to indicate high and low values.
Horizontal Linear Gauge — a linear horizontal gauge with a slider,
Hyperlink Button — acts as a hyperlink to another page or a URL.
Hyperlink Image — acts as a hyperlink to another page or a URL.
Hyperlink Text — acts as a hyperlink to another page or a URL.
Image — an image file container.
Left 90 Degree Gauge — a quarter-circle gauge.
List Box — a simple list used for item selection.
Media Player — plays audio and videos.
One Input Calculator — a program block that performs calculations on a single input value.
Point Data Table — a table consisting of all available data points.
Polynomial Calculator — a program block that calculates the result of a polynomial expression.
Progress Bar — an expanding/shrinking progress bar.
Radio Button — a button that offers a choice of mutually exclusive options.
Range Mapper — a program block that maps an input to an output, using ranges.
Rising/Falling Indicator — a display that changes according to the rise or fall of a value.
Semi-circular Gauge — a semi-circular gauge.
Series Chart — displays data in chart format - bars, lines, pie, etc.
Shining Light — an indicator light that can flash and change color.
Simple Button — a simple, clickable button.
Simple Check Box — toggles between two states.
Simple Ellipse — a simple ellipse with editable appearance and properties.
Simple Path — a path that can create any shape.
Simple Rectangle — a simple rectangle with editable appearance and properties.
Slider — a scale with an adjustable slider to control or view values.
Symbol — a container for over 4000 symbols.
System Information — a program block that can access system, user, and page information.
Text Entry Field — a simple textbox used for data entry.
Text Label — a textual display with no entry field.
Three Point Slider — a horizontal gauge that shows up to three data points on a slider.
Time Picker — allows a user to select a time.
Timer — a program block executes that provides timer and counter behavior.
Toggle Button — a push button with an optional two-state toggle.
Top Sweep Gauge — a horizontal curved gauge.
Trend — two chart controls can track up to 3 or 8 data points.
Two Input Calculator — a program block that performs calculations on two input values.
Vertical Linear Gauge — a linear vertical gauge with a slider.
DataHub Scripting
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
DataHub ODBC Scripting
1. Introduction
1.1. Overview
1.2. Setting up a DSN (Data Source Name)
1.3. Working with MS Access
2. Tutorials
2.1. Tutorial 1: Writing new rows to a table, based on a trigger - Multi-Threaded Version
2.2. Tutorial 2: Writing new rows to a table, based on a trigger - Single-Threaded Version
2.3. Tutorial 3: Updating existing rows, or writing new ones
2.4. Tutorial 4: Writing data from a database to a DataHub instance
2.5. Viewing data from a web browser
3. An Explanation of the Tutorial Code
3.1. Define the Application Object
3.2. Interactions with the Database
3.2.1. Connecting to the Database
3.2.2. Creating a Gamma Class from a Database Table
3.2.3. Querying Rows from the Database
3.2.4. Inserting Rows into a Database
3.2.5. Updating Existing Rows in a Database
3.2.6. Creating a Database Table
3.3. Set up Event Handlers
3.4. Shut Down
4. Multi-Threaded ODBC Interface
4.1. How-To
4.1.1. Create an ODBCThread Instance
4.1.2. Attach Event Callbacks
4.1.3. Configure Startup Actions
4.1.4. Start the Database Thread
4.2. Store and Forward
4.2.1. Time Delayed Writes
4.3. Example
5. Classes
DATE_STRUCT — contains dates (y,m,d).
ODBCColumn
ODBCConnection — allocates a connection handle.
ODBCDescriptor — allocates a descriptor handle.
ODBCEnvironment — allocates an environment handle.
ODBCHandle — a parent class for connections, descriptors, environments, and statements.
ODBCResult
ODBCStatement — allocates a statement handle.
ODBCThread — configures the multi-threaded ODBC interface.
ODBCThreadResult — the results of an SQL command.
SQLGUID — holds ID strings.
SQL_DAY_SECOND_STRUCT — contains time data for SQL_INTERVAL_STRUCT.
SQL_INTERVAL_STRUCT — contains interval data for SQL queries.
SQL_INTERVAL_STRUCT_intval — contains year/month or day/second info for SQL_INTERVAL_STRUCT.
SQL_NUMERIC_STRUCT — specifies number precision and sign.
SQL_YEAR_MONTH_STRUCT — contains year and month data for SQL_INTERVAL_STRUCT.
TIMESTAMP_STRUCT — contains timestamp data (y,m,d,h,m,s, etc.).
TIME_STRUCT — contains time data (h,m,s).
6. Global Functions
ODBC_AllocEnvironment — creates an ODBCEnvironment.
ODBC_ValueString
7. Constants
DataHub Windows Scripting
1. Introduction
1.1. Overview
1.2. Auto-Generation
1.2.1. Documentation
2. Tutorials
2.1. Making a Window
2.2. Displaying Data
2.3. Entering Data
2.4. A complete demo program: WindowsExample.g
2.5. Sample Code: ShowImage.g
2.6. Sample Code: ListBoxExample.g
2.7. Sample Code: TreeViewDemo.g
2.8. Sample Code: Browse DataHub Points using TreeViewExample.g
3. Widgets
G3StateButton — a 3-state button.
GAnimateCtrl — an animation control.
GBitmapButton — a bitmap button.
GButton — a button.
GCheckBox — a check box.
GCheckListViewCtrl — purpose is not yet documented.
GColorDialog — a color-selection dialog box.
GComboBox — a list box combined with a static or edit control.
GComboBoxEx — a combo box with support for image lists.
GDateTimePickerCtrl — a way to enter a date and time, based on CDateTimeCtrl.
GDialog — a dialog box.
GDragListBox — allows listed items in a list box to be moved.
GEdit — a text-entry box.
GFileDialog — a dialog box for opening and saving files.
GFlatScrollBar — a scrollbar with an enhanced interface, based on FlatScrollBar.
GFolderDialog — a dialog box to manage folders, based on Folder Dialog.
GFontDialog — a dialog box to manage fonts, based on Font Dialog.
GGroupBox — a rectangle that groups controls, based on Group Box.
GHeaderCtrl — a header for columns of text or numbers.
GHotKeyCtrl — allows the creation of a hot key.
GHyperLink — displays a link to a web page, based on HyperLink.
GIPAddressCtrl — an entry field for an IP address.
GLinkCtrl — embeds a hypertext link in a window.
GListBox — a box with a list of items.
GListViewCtrl — determines how lists are displayed, based on ListView Control.
GMonthCalendarCtrl — a control for setting dates and times, based on MonthCalendar Control.
GPageSetupDialog — a control for print page setup options.
GPagerCtrl — a container for a window without enough area to display its content.
GPrintDialog — a print dialog window.
GProgressBarCtrl — a rectangle that fills over time, based on ProgressBar Control.
GRadioButton — a radio button, based on CButton.
GReBarCtrl — a container for a child window.
GRichEditCtrl — a text entry and editing window.
GScrollBar — a scroll-bar control.
GStatic — a static control for text strings, rectangles, bitmaps, etc.
GStatusBarCtrl — an area at the bottom of a window that displays information.
GTabCtrl — a tabbed label for marking multiple pages.
GToolBarCtrl — a toolbar with one or more buttons.
GToolTipCtrl — a pop-up window with a line of text.
GTrackBarCtrl — a slider with optional tick marks, based on TrackBar Control.
GTreeViewCtrl — displays a hierarchy of nodes as a tree, based on TreeView Control.
GTreeViewCtrlEx — an extended TreeViewCtrl.
GUpDownCtrl — a pair of arrows for incrementing and decrementing values, based on UpDown Control.
GWindow — methods for manipulating a window.
GWindowBase — the base for most of these widgets, based on CWindow.
4. Global Functions
5. Non-Widget Classes
6. Constants
DataHub APIs for C++, Java, and .NET
1. Introduction
1.1. Preliminaries
1.2. C++ Programming
1.3. Java Programming
1.4. .NET Programming
1.5. Example Programs
2. The DataHubConnector Class
2.1. Overview
2.2. Categorized List of Methods
2.3. Making Callbacks
3. The DataHubPoint Class
3.1. Overview
3.2. Categorized List of Methods
1. GNU General Public License
2. GNU Lesser General Public License
DataHubConnector Methods
DataHubConnector — creates a DataHubConnector object.
~DataHubConnector — destroys a DataHubConnector object.
activeHeartbeatTimers — determines if both heartbeat timers are active.
addPointValue — adds a specified amount to a DataHub point value.
appendPointValue — appends a string to a DataHub point.
cancelHeartbeatTimers — cancels the heartbeat and timeout timers.
cancelReconnectionTimer — stops the delay timer for reconnection attempts.
closeConnection — closes the connection to the DataHub instance.
createPoint — creates a DataHub point.
dividePointValue — divides the value of the named point by the specified value.
escapedString — prepares a string for use with writeCommand (Java and C# only).
getCnxState — retrieves the operational state of the connector object.
getCnxStateString — retrieves a string corresponding to the operational state.
getCnxSubStateString — provides detailed information on the connection state (C++ only).
getDefaultDomain — returns the current default domain.
getErrString — retrieves the last error string (C++ only).
getHeartbeat — retrieves the heartbeat timer period.
getHostName — retrieves the host name connection parameter.
getPort — retrieves the port connection parameter.
getReconnectionDelay — retrieves the delay time between reconnection attempts.
getServiceName — retrieves the port service name connection parameter (C++ only).
getTimeout — retrieves the timeout timer period.
initializePointCache — initializes local point cache usage.
isConnected — indicates whether a connection has been established.
isConnecting — indicates whether a connection attempt is in progress.
lookupPoint — accesses a point from the point cache.
multiplyPointValue — multiplies a DataHub point value by a specified amount.
openConnection — attempts to establish a connection to the DataHub instance.
readPoint — gets the value of a DataHub point.
registerDomain — registers to receive updates from domain points.
registerPoint — registers to receive updates from a DataHub point.
retryConnection — opens a new connection to the DataHub instance (C++ only).
sendBinaryPointMessages — formats data in binary mode (C++ only).
sendLispMessage — sends a message to the DataHub instance (C++ only).
sendLogin — transmits the user name and password.
setConnectionParms — sets the connection parameters.
setDefaultDomain — sets the default domain.
setHeartbeatTimes — sets the period of the heartbeat timers.
setPointLock — sets the lock attributes of a DataHub point.
setPointSecurity — sets the security attributes of a DataHub point.
setReconnectionDelay — sets the delay time between reconnection attempts.
setUsername — stores a user name and password for this connection.
shutdown — prepares for an application shutdown or disconnect (Java and C# only).
startHeartbeatTimers — starts the heartbeat and timeout timers.
startReconnectionTimer — starts the delay timer for reconnection attempts.
unregisterPoint — stops receiving updates from a DataHub point.
writeCommand — sends a command to the DataHub instance (Java and C# only).
writePoint — writes a new value to a DataHub point.
Callback Methods
onAlive — a virtual method invoked on receipt of a heartbeat from the DataHub instance.
onAsyncMessage — a virtual method invoked on receipt of a DataHub message.
onConnectionFailure — a virtual method invoked when a connection or attempt to connect fails.
onConnectionSuccess — a virtual method invoked when a connection is established.
onError — a virtual method invoked on receipt of an error message.
onPointChange — a virtual method invoked on receipt of a point value change.
onPointEcho — a virtual method invoked on receipt of a locally changed point value.
onStatusChange — a virtual method invoked on change of status.
onSuccess — a virtual method invoked on receipt of a success message.
DataHubPoint Methods
DataHubPoint — constructs a DataHubPoint object.
~DataHubPoint — destroys a DataHubPoint object.
operator= — assigns a new value to a DataHubPoint object (C++ only).
clear — clears the point.
copy — copies the point data.
getConfidence — retrieves the user's point confidence.
getDateString — generates a 'standard' timestamp data/time representation.
getDoubleValue — retrieves the point data as a double-typed value.
getFlags — retrieves the flags property of the point.
getIntValue — retrieves the point data as an int-typed value.
getListeners — retrieves listeners on the point (Java only).
getLocked — retrieves the locked property of the point.
getName — retrieves the point name.
getNanoseconds — retrieves the timestamp nanoseconds component.
getQuality — retrieves the point quality.
getQualityString — generates a string representing the point quality.
getSeconds — retrieves the timestamp seconds component.
getSecurity — retrieves the security property of the point.
getStringValue — retrieves the point data as a string.
getType — retrieves the point data type.
getUserdata — retrieves the user object associated with the point.
qualifyName — creates a point name string qualified by a domain name.
removeListener — removes a listener from the point (Java only).
setConfidence — sets the user's confidence in a point.
setInfo — sets the information properties of a point.
setLocked — sets the locked property of the point.
setName — assigns a name to the point.
setQuality — sets the point quality.
setSecurity — sets the security property of the point.
setTimeStamp — sets the point timestamp in various ways.
setFlags — sets the flags property of the point.
setUserdata — associates the point with a user object.
setValue — sets the point data to the specified type and value.
setValueFromString — sets the point data to the value represented by a string.
unqualifyName — removes the domain name qualifier from a point name.
Gamma scripting language
Programmers Manual
1. Introduction
1.1. What is Gamma?
2. Getting Started
2.1. Interactive Mode
2.2. Executable Programs
2.3. Symbols and Values
3. Basic Data Types and Mechanisms
3.1. Numeric Types
3.1.1. Integer
3.1.2. Real
3.1.3. Fixed-point Real
3.1.4. Number Operators
3.2. Logical Types
3.3. Strings
3.4. Lists and Arrays
3.5. Constants
3.6. Operators and Expressions
3.7. Comments
3.8. Reserved Words
3.9. Memory Management
4. Tutorial I
4.1. Lists
4.2. "Hello world" program
5. Control Flow
5.1. Statements
5.1.1. Conditionals
5.1.2. Loops
5.1.3. Goto, Break, Continue, Return
5.2. Function Calls
5.3. Event Handling
5.3.1. Interprocess Communication Message Events
5.3.2. Timers
5.3.2.1. Setting a timer
5.3.2.2. Canceling a Timer
5.3.2.3. The TIMERS variable:
5.3.2.4. Blocking timers from firing
5.3.2.5. timer_is_proxy function
5.3.3. Symbol Value Events (Active Values)
5.3.4. Cogent DataHub instance Point Events (Exception Handlers)
5.3.5. Windowing System Events
5.3.5.1. GUI Event Handlers (Callbacks)
5.3.6. Signals
5.3.6.1. block_signal & unblock_signal
5.4. Error Handling
5.4.1. Situations that might cause Gamma to crash
6. Tutorial II
6.1. Error Handling - try/catch, protect/unwind
6.2. Dynamic Scoping
6.3. Error Handling - interactive session
7. Functions and Program Structure
7.1. Function Definition
7.2. Function Arguments
7.2.1. Variable number of arguments
7.2.2. Optional arguments
7.2.3. Protection from evaluation
7.2.4. Variable, optional, unevaluated arguments
7.2.5. Examples
7.3. Function Renaming
7.4. Loading files
7.5. The main Function
7.6. Executable Programs
7.7. Running a Gamma Program
7.8. Command Line Arguments
8. Object Oriented Programming
8.1. Classes and Instances
8.1.1. Instances
8.2. Methods
8.3. Inheritance
8.4. Instance Variables
8.5. Class Variables
8.6. Constructors and Destructors
8.7. Polymorphism
8.7.1. Operator Overloading
8.8. Binary Classes and User Classes
9. Tutorial III
9.1. Classes and OOP
10. Interactive Development and Debugging
10.1. Interactive Mode Implementation
10.2. Getting On-Line Help for Functions
10.3. Examining Variables in a Class or Instance
10.4. Using the Debug Prompt
10.5. Debugging a program
10.5.1. Interacting with an Active Program
10.5.2. Trapping and Reporting Errors
10.5.3. Determining Error Location
10.5.4. Filtering Object Query Output
11. Advanced Types and Mechanisms
11.1. Symbols
11.1.1. Undefined symbols
11.1.2. Uniqueness of Symbols
11.1.3. Properties
11.1.4. Predefined Symbols
11.2. Evaluation
11.2.1. Evaluation of a Symbol
11.2.2. Evaluation of a List
11.2.3. Evaluation to Itself
11.3. Literal Syntax and Evaluation
11.3.1. Literal Expressions
11.3.2. Deferring Expression Evaluation
11.3.3. Literal Function Arguments
11.3.4. Partially Evaluated Literal
11.3.5. Constructing Variable Names at Run-time
11.3.6. Literal Array Syntax
12. Input and Output
12.1. Referencing Files
12.2. Lisp and Gamma I/O mechanisms
12.3. Writing
12.3.1. Print vs. Princ
12.3.2. Write vs. Writec
12.3.3. Terpri
12.3.4. Pretty Printing
12.3.5. Printing Circular References
12.4. Reading
12.4.1. Reading Gamma Expressions
12.4.2. Reading Arbitrary ASCII Data
12.4.3. Reading Binary Data
13. Special Topics
13.1. Modifying QNX Process Environment Variables
13.2. QNX 4 Interprocess Communication (IPC)
13.3. Cogent IPC
13.3.1. Cogent IPC Service Modules
13.3.2. Cogent IPC Advanced services
13.3.2.1. Cogent IPC Messages
13.3.2.2. Asynchronous Messages
13.3.2.3. Pseudo-Asynchronous Messages
13.3.2.4. Task Started & Death Notification
13.3.2.5. Automatic Handling of QNX 4 receive and reply
13.3.2.6. IPC Initialization
13.3.2.7. Locating Tasks
13.3.2.8. Transmitting Character Strings
13.3.3. Cogent DataHub
13.3.4. Cogent DataHub Exceptions and Echos
1. Function List
2. GNU Lesser General Public License
Gamma Reference
Symbols and Literals
Data Types and Predicates — testing for data types.
undefined_p, undefined_symbol_p — test for undefined types and symbols.
Literals — defined for integers, reals, strings, and symbols.
Predefined Symbols — a table.
Reserved Words — a table.
t — a logically true value.
nil — the logically false value.
gamma, phgamma — start Gamma and Gamma/Photon from the shell prompt.
Operators
Operator Precedence and Associativity — a table.
Arithmetic Operators — (+, -, *, /, %)
Assignment Operators — (=, :=, ::=)
Binary Operator Shorthands — (+=, -=, *=, /=, %=, &=, ^=, <<=, >>=)
Bitwise Operators — (<<, >>, ~ , &, |, ^)
Class Operators — (., ..)
Comparison Operators — (!=, <, <=, ==, >, >=)
Evaluation Order Operators , ( )
Increment and Decrement Operators — (++, --)
Logical Operators — (!, &&, ||)
Quote Operators — (#, `, @)
Symbol Character Operators — (\, $)
Ternary Operator — ( ? : )
Statements
class — defines a class.
condition — tests conditions.
for — checks a condition and performs a statement.
function — creates a new function.
if — conditionally evaluates statements.
local — allows for implementing local variables within functions.
method — defines a method for a given class.
progn, prog1 — group several statements into one expression.
protect unwind — evaluates protected code, despite errors.
switch — tests arguments with conditions.
try catch — catches errors in the body code.
while — iterates, evaluating a statement.
with — traverses an array or list performing a statement.
Core Functions
call — calls a class method for a given instance.
class_add_cvar — adds new class variables.
class_add_ivar — adds an instance variable to a class.
class_name — gives the name of the class.
class_of — gives the class definition of a given instance.
defclass — is the function equivalent of the class statement.
defmacro, defmacroe — are the Lisp equivalents of the macro function.
defun, defune, — are the function equivalents of the function statement.
defmethod — is the function equivalent of the method statement.
defvar — defines a global variable with an initial value.
destroy — destroys a class instance.
eq, equal — compare for identity and equivalence.
error — redirects the interpreter.
eval — evaluates an argument.
eval_list — evaluates each element of a list.
eval_string — evaluates a string.
force, forceq, forceqq — assign a value to a symbol, forcing the evaluation of change functions for the symbol.
funcall — provides compatibility with other Lisp dialects.
function_args — lists the arguments of a function.
function_body — gives the body of a user-defined function.
function_name — gives the name of a function.
getprop — returns a property value for a symbol.
has_cvar — queries for the existence of a class variable.
has_ivar — queries for the existence of an instance variable.
instance_vars — finds all the instance variables of a class or instance.
is_class_member — checks if an instance or class is a member of a class.
ivar_type — returns the type of a given instance variable.
macro — helps generate custom functions.
new — creates a new instance of a class.
parent_class — returns the closest parent (base) of a class or instance.
print_stack — prints a Gamma stack.
properties — should never be used.
quote, backquote — correspond to Quote Operators.
require, load — load files.
set, setq, setqq — assign a value to a symbol.
setprop — sets a property value for a symbol.
setprops — lists the most recent property value settings.
trap_error — traps errors in the body code.
unwind_protect — ensures code will be evaluated, despite errors in the body code.
whence — gives input information.
Lists and Arrays
append — concatenates several lists into a single new list.
aref — returns an array expression at a given index.
array — constructs an array.
array_split — partitions a list or array into multiple lists or arrays.
array_to_list — converts an array to a list.
aset — sets an array element to a value at a given index.
assoc, assoc_equal — search an association list for a sublist.
bsearch — searches an array or list for a element.
car, cdr, and others — return specific elements of a list.
cons — constructs a cons cell.
copy — makes a copy of the top list level of a list.
copy_tree — copies the entire tree structure and elements of a list.
delete — removes an element from an array.
difference — constructs a list of the differences between two lists.
find, find_equal — search a list using the eq and equal functions.
insert — inserts an array value at a given position.
intersection — constructs a list of all the elements found in both of two lists.
length — counts the number of elements in a list or array.
list, listq — create lists.
list_to_array — converts a list to an array.
make_array — creates an empty array.
nappend — appends one or more lists, destructively modifying them.
nremove — removes list items, destructively altering the list.
nreplace, nreplace_equal — replace elements in a list.
nth_car, nth_cdr — iteratively apply the car and cdr functions to a list.
remove — removes list items without altering the list.
reverse — reverses the order of list elements.
rplaca, rplacd — replace the car and cdr of a list.
shorten_array — reduces or expands the size of an array.
sort — sorts a list or array, destructively modifying the order.
union — constructs a list containing all the elements of two lists.
Strings and Buffers
bdelete — deletes a number of bytes from a buffer.
binsert — inserts a value into a buffer.
buffer — constructs a buffer.
buffer_to_string — converts a buffer to a string.
format — generates a formatted string.
make_buffer — creates a new, empty buffer.
open_string — allows a string to be used as a file.
parse_string — parses an input string.
raw_memory — tells the amount of memory in use.
shell_match — compares string text to a pattern.
shorten_buffer — reduces the size of a buffer.
strchr, strrchr — search a string for an individual character.
strcmp, stricmp — compare strings.
string — constructs a string.
stringc — constructs a string in Lisp-readable form,
string_file_buffer — queries a string file for its internal buffer.
string_split — breaks a string into individual words.
string_to_buffer — creates a buffer object from a string.
strcvt — converts the Windows character set of a string.
strlen — counts the number of characters in a string.
strncmp, strnicmp — compare two strings and return a numeric result.
strrev — reverses the order of characters in a string.
strstr — finds the location of a given substring.
substr — returns a substring for a given location.
tolower — converts upper case letters to lower case.
toupper — converts lower case letters to upper case.
Data Type Conversion
bin — converts numbers into binary form.
char — generates an ASCII character from a number.
char_val — generates a character's numeric value.
dec — converts numbers into base-10 form.
hex — converts numbers into hexadecimal form.
int — converts to integer form.
number — attempts to convert an expression to a number.
oct — converts numbers into octal form.
symbol — constructs a symbol from a string.
Math
acos, asin, atan, atan2 — perform trigonometric arc functions.
and, not, or — are the same as the corresponding Logical Operators.
band, bnot, bor, bxor — perform bitwise operations.
ceil — rounds a real number up to the next integer.
cfand, cfor — perform and and or functions with confidence factors.
conf, set_conf — query and set confidence factors.
cos, sin, tan — perform trigonometric functions.
div — divides, giving an integer result.
exp — calculates an exponent of the logarithmic base (e).
floor — rounds a real number down to its integer value.
log, log10, logn — calculate logarithms.
isnan — identifies invalid or illegal numbers.
isinf — determines if a number is infinite.
neg — negates.
pow — raises a base to the power of an exponent.
random — generates random numbers from 0 to 1.
round — rounds a real number up or down to the nearest integer.
set_random — starts random at a different initial number.
sqr — finds the square of a number.
sqrt — finds the square root of a number.
Input/Output
close — closes an open file.
fd_close — closes a file identified by a file descriptor.
fd_data_function — attaches a write-activated callback to a file.
fd_eof_function — attaches an eof-activated callback to a file.
fd_open — opens a file or device and assigns it a file descriptor.
fd_read — reads a buffer or string from a file identified by a file descriptor.
fd_to_file — creates a file pointer from a descriptor.
fd_write — writes a buffer or string to a file identified by a file descriptor.
fileno — creates a file descriptor from a pointer.
ioctl — performs control functions on a file descriptor.
open — attempts to open a file.
pipe — creates a pipe.
princ, print, pretty_princ, pretty_print — write to the standard output file.
pty, ptytio — run programs in a pseudo-tty.
read — reads a Lisp expression from a file.
read_char, read_double, read_float, read_long, read_short — read the next character, double, float, long or short value in binary representation from the input file.
read_eval_file — reads a file, evaluating and counting expressions.
read_line — reads a single line of text.
read_n_chars — reads and stores characters.
read_until — reads characters, constructing a string as it goes.
seek — sets the file position for reading or writing.
ser_setup — sets parameters for a serial port device.
tell — indicates file position.
terpri — prints a newline to an open file.
unread_char — attempts to replace a character to a file for subsequent reading.
write, writec, pretty_write, pretty_writec — write an expression to a file.
write_n_chars — writes characters from a buffer to a file.
File System
absolute_path — returns the absolute path of the given file.
access — checks a file for various permissions.
basename — gives the base of a filename.
cd — changes the working directory.
chars_waiting — checks for characters waiting to be read on a file.
directory — returns the contents of a directory.
dirname — returns the directory path of a file.
drain — modifies end-of-file detection.
file_date — gives the file modification date.
file_size — gives the file size.
flush — flushes any pending output on a file or string.
getcwd — gets the current working directory.
is_busy — determines if a file is busy.
is_dir — determines if a file is a directory.
is_file — determines if a file exists.
is_readable — determines if a file is readable.
is_writable — determines if a file is writable.
mkdir — creates a new sub-directory.
path_node — gives the node number of a path in a QNX 2 path definition.
rename — renames a file.
root_path — strips the final file or directory name from a path.
tmpfile — generates temporary output file names.
unbuffer_file — causes a file to be treated as unbuffered on both input and output.
unlink — deletes a file.
OS APIs
atexit — evaluates code before exiting a program.
block_signal, unblock_signal — delimit signal blocking.
errno — detects and numbers errors.
exec — executes a program.
exit_program — terminates the interpreter.
fork — duplicates a process.
getenv — retrieves the value of an environment variable.
gethostname — gets the computer's host name.
getnid — returns the local node number.
getpid — returns the program ID.
getsockopt, setsockopt — get and set a socket option.
kill — sends a signal to a process.
nanosleep — pauses the interpreter for seconds and nanoseconds.
setenv — sets an environment variable for the current process.
shm_open — opens shared memory objects.
shm_unlink — removes shared memory objects.
signal — defines an expression to be evaluated at an OS generated signal.
sleep, usleep — suspend execution.
strerror — retrieves an error message.
system — treats its argument as a system command.
tcp_accept — forks a new TCP socket on the server side to accept a new connection.
tcp_connect — creates a client-side TCP socket connection.
tcp_listen — creates a server-side TCP socket connection.
wait — waits for process exit status.
Dynamic Loading
AutoLoad — allows for run-time symbol lookup.
autoload_undefined_symbol — checks undefined symbols for AutoLoad.
AutoMapFunction — maps a C function to a Gamma function.
ClearAutoLoad — removes all AutoLoad rules.
dlclose — closes an open dynamic library.
dlerror — reports errors in dl functions.
dlfunc — reserved for future use.
DllLoad — loads dynamic libraries.
dlmethod — reserved for future use.
NoAutoLoad — removes selected AutoLoad rules.
dlopen — loads a dynamic library from a file.
Profiling and Debugging
allocated_cells — gives the number of allocated and free cells.
eval_count — counts evaluations made since a program started.
free_cells — returns the number of available memory cells.
function_calls — tells how often a function was called during profiling.
function_runtime — gives the time a function has run during profiling.
gc — runs the garbage collector.
gc_blocksize — for internal use only.
gc_enable — for internal use only.
gc_newblock — for internal use only.
gc_trace — controls the tracing of garbage collection.
profile — collects statistics on function usage and run time.
set_autotrace — is reserved for future use.
set_breakpoint — is reserved for future use.
time — gives command execution times.
trace, notrace — turn tracing on or off.
Miscellaneous
apropos — finds all defined symbols in the current interpreter environment.
create_state, enter_state, exit_state — are part of the SCADALisp exception-driven state machine mechanism.
gensym — generates a unique symbol.
modules — is obsolete, and returns nothing of value.
stack — lists all functions called so far.
IPC
add_hook — hooks a function to an event.
close_task — closes a task opened by locate_task.
_destroy_task — should never be used.
init_async_ipc — requests queue information from a task.
init_ipc — sets up necessary data structures for IPC.
isend — sends a synchronous message and doesn't wait for the result.
locate_task — finds and connects to tasks by name.
locate_task_id — finds and connects to tasks by task ID and network node.
name_attach — attaches a name to a task.
nserve_query — puts information from nserve into an array.
remove_hook — removes a hooked function.
run_hooks — runs a hooked function.
send — transmits expressions for evaluation.
send_async — transmits expressions asynchronously.
send_string — transmits strings for evaluation.
send_string_async — transmits a string asynchronously.
taskdied, taskstarted — internal functions that call another function when a task starts or stops.
task_info — gets information from a task descriptor.
Events and Callbacks
add_set_function — sets an expression to be evaluated when a given symbol changes value.
flush_events — handles all pending events, then exits.
next_event, next_event_nb — wait for an event and call the event handling function.
remove_set_function — removes a set function from a symbol.
when_set_fns — returns all functions set for a symbol.
Time, Date, and Timers
after — a timer that initiates an action after a period of time.
at — a timer that initiates an action at a given time, or regularly.
block_timers, unblock_timers — block and unblock timer firing.
cancel — removes a timer from the set of pending timers.
clock, nanoclock — get the OS time.
date — gets the OS date and time; translates seconds into dates.
date_of — is obsolete, see date
every — a timer that initiates an action every number of seconds.
gmtime — transforms Unix time to UTC time and date in ASCII format.
Iso8601ToUnixTime — converts from ISO 8601 time to Unix time.
localtime — transforms Unix time to local time and date in ASCII format.
mktime — converts the ASCII date and time data in a tm class to Unix time.
timer_is_proxy — controls timer handling in Gamma.
UnixTimeToIso8601 — converts from Unix time to ISO 8601.
Cogent DataHub
add_exception_function, add_echo_function — assign functions for exceptions or echoes on a point.
lock_point — locks or unlocks points.
point_locked — indicates if a point is locked.
point_nanoseconds — gives the nanoseconds from point_seconds that a point value changed.
point_seconds — gives the time the point value changed.
point_security — gives the security level of a point.
read_existing_point, read_point — retrieve points.
register_all_points — registers an application to receive exceptions for all points.
register_exception — not yet documented.
register_point, register_existing_point — register an application to receive exceptions for a single point.
remove_echo_function — removes an echo function from a symbol.
remove_exception_function — removes an exception function from a symbol.
secure_point — alters the security level on a point.
set_domain — sets the default domain for future calls.
set_security — changes the security level for the current process.
unregister_point — stops echo and exception message sending.
when_echo_fns, when_exception_fns — indicate the functions for echos or exceptions on a point.
write_existing_point, write_point — write point values.