Page History

Datasets → Tutorial | Concept | How-to Guide | Reference

Overview

The Dataset Engine orchestrates:

• Synchronous and asynchronous database operations
• Connection pooling and thread management
• Client/server domain tag mapping
• Query execution through TServer services
• Result set propagation
• Multi-database coordination

Understanding the engine helps when:

• Optimizing database performance
• Managing concurrent operations
• Implementing client-specific data
• Troubleshooting connection issues

Architecture

Process Separation

Execution Process And Database Connections

The Dataset Module, specifically the TRunModule.exe (Dataset) process, reads all project configurations relevant to this module but does not directly interface with databases. The TServer provides database access services. The Dataset Module only uses TServer-provided services.

The Dataset Module runs as

TRunModule.exe (Dataset)

:

• Reads all dataset configurations
• Does NOT directly connect to databases
• Consumes TServer database services
• Manages tag mapping and updates

TServer provides:

• Actual database connections
• SQL execution services
• Connection pooling
• Transaction management

Connection Management

Single Thread per DB

• Each DB configuration creates ONE connection
• Single execution thread per database
• Sequential command execution

Parallel Execution

For concurrent operations to same database:

DB1 → Production Database (Thread 1)
DB2 → Production Database (Thread 2)
DB3 → Production Database (Thread 3)

Create multiple DB connections to same database for parallelism.

Execution Methods

Asynchronous Execution (Default)

Trigger: Property changes (Select, Insert, Update, Delete)

Flow:

1. Property triggered (screen/script)
2. Request propagated to server
3. Dataset Module receives request
4. TServer executes database operation
5. Results returned to Dataset Module
6. Tags mapped and updated
7. Execution continues in parallel

Advantages:

• Non-blocking operation
• Better performance
• Prevents UI freezing
• Allows parallel operations

Use Cases:

• Display queries
• Background updates
• Report generation
• Real-time monitoring

Synchronous Execution

Trigger: Method calls (SelectCommand, ExecuteCommand)

Flow:

1. Method called
2. Execution PAUSES
3. Dataset Module calls TServer
4. Database operation completes
5. Results returned
6. Tags mapped
7. Execution RESUMES

Advantages:

• Guaranteed completion
• Sequential logic
• Immediate results
• Transaction support

Risks:

• Can freeze UI if called from screen
• Blocks thread execution
• Performance bottlenecks

Use Cases:

• Script tasks
• Sequential operations
• Transaction requirements
• Data validation

Tag Domain Mapping

Execution Context

Tag mapping occurs in the original call domain:

Client-Initiated Calls:

• From displays or client scripts
• Mapping uses client domain
• Results visible to specific client
• Isolated from other clients

Server-Initiated Calls:

• From server scripts or tasks
• Mapping uses server domain
• Results visible project-wide
• Shared across all clients

Domain Selection Strategy

Performance Optimization

Connection Pooling

• Reuse existing connections
• Minimize connection overhead
• Configure pool size appropriately

Query Optimization

sql

-- Use parameters to prevent recompilation
SELECT * FROM Table WHERE ID = @id

-- Limit result sets
SELECT TOP 100 * FROM LargeTable

-- Use appropriate indexes
CREATE INDEX idx_timestamp ON Data(Timestamp)

Asynchronous Patterns

csharp

// Good: Asynchronous from screen
@Dataset.Table.MyTable.SelectCommand = "SELECT * FROM Data";

// Bad: Synchronous from screen (blocks UI)
@Dataset.Table.MyTable.SelectCommandWithStatus();

Batch Operations

• Group multiple operations
• Use transactions for consistency
• Minimize round trips

Threading Model

Dataset Module Thread

• Main coordination thread
• Manages request queue
• Handles tag mapping

TServer Database Threads

• One per DB connection
• Sequential execution per thread
• Connection isolation

Client Request Threads

• Asynchronous request handling
• Non-blocking UI operations
• Parallel client support

Error Handling

Connection Failures

• Automatic retry logic
• Connection pooling recovery
• Error event propagation

Query Errors

• Exception capture in TServer
• Error property population
• Tag mapping skipped on error

Timeout Management

• Configurable command timeout
• Connection timeout settings
• Automatic cleanup

Best Practices Checklist 

•  Prefer asynchronous - Use properties over methods
•  Avoid UI blocking - No synchronous calls from screens
•  Use appropriate domains - Client for user, Server for shared
•  Pool connections - Reuse database connections
•  Optimize queries - Index, parameterize, limit
•  Handle errors - Check status properties
•  Monitor performance - Track execution times

Troubleshooting

Slow queries:

• Check execution plan
• Add appropriate indexes
• Reduce result set size
• Use asynchronous execution

Connection issues:

• Verify TServer running
• Check connection string
• Review firewall rules
• Monitor connection pool

Tag mapping problems:

• Verify domain selection
• Check tag existence
• Review mapping configuration
• Confirm execution context

Thread blocking:

• Avoid synchronous in UI
• Use Script Tasks
• Implement async patterns
• Monitor thread pool

Databases Connections

For each configured DB, only one access connection is created, meaning there's only one execution thread for each DB. If parallel execution of commands to the same database is required, you can create more than one DB pointing to the same database. The Dataset Module is a vital system component, functioning independently via TRunModule.exe (Dataset). Despite not interacting directly with databases, the Dataset Module reads project configurations and utilizes services within TServer to access databases. As a result, all database connections and calls occur in TServer.

Database Interactions

The Dataset Module provides two critical methods for executing data requests: 

• Synchronous
• Asynchronous

Understanding the differences between these methods, their default behaviors, and when to use each is crucial for optimizing performance and avoiding potential bottlenecks in your project.

Asynchronous Execution

This method is generally more performant and can help avoid potential locks. When properties in both Tables and Queries, such as the Select property, are triggered, the execution becomes Asynchronous. After the trigger, the execution usually continues. At the same time, the property is propagated from the trigger point, such as a screen or a script, to the server in parallel. It then synchronizes with the Dataset Module, which calls upon the necessary services from TServer to interface with the database. Upon TServer's return with the execution of the Select for the Dataset module, the result is updated in the properties and attributes of the module. Lastly, the mapping process is executed, updating Tags' values to the entire project.

Synchronous Execution

Certain methods have a Synchronous Execution. For example, when calling the SelectCommand method, the solution execution is paused until the Dataset Module carries out the service call to TServer, which interfaces with the database and returns the result to the Dataset Module. The Dataset Module then performs Tag mapping and returns the result, allowing the execution to resume.

Since the execution is paused, it's crucial to use synchronous calls carefully within mono-threaded code behind screens, whether WPF or HTML5. While synchronous execution can be appropriate in some instances, overuse can lead to performance issues. Mechanisms like the Script task or Action Server Request can facilitate asynchronous execution without using attributes. This is particularly useful when the result needs to be handled even after an asynchronous execution has been completed.

Client Vs. Server Tags in Mapping Results

In the Dataset Module, it's possible to utilize Tags from the client domain during Tag mapping. This capability provides additional flexibility when managing data in your project. When executing a synchronous or asynchronous command, the Dataset Module, not the TServer, carries out the tag assignment within the original domain of the call. 

If a call is initiated from a client, such as a screen or client script, the mapping operation between the received values and the tags occurs after TServer returns the result to the Dataset module. In this scenario, client domain Tags can be used in the mapping. The choice of the Tag domain is essential for controlling the scope of data availability. If you wish the data to be available project-wide, server domain Tags are the appropriate choice. However, if the data's scope should be confined to the client that initiated the call, client domain tags would be the best option.

In this section...