Page History

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

Configuration Properties

Creating Dataset Files

1. Navigate to Datasets → Files
2. Click Plus icon
3. Configure:
   • Name: Unique identifier
   • Description: Documentation
4. Click OK
5. Set properties:
   • FileName: Target file path
   • FileType: Select format
   • Objects: Map tags

File Types

ASCII Files

Plain text, single-byte encoding:

Tag1=100
Tag2=200.5
Tag3=Active

Unicode Files

Multi-byte character support:

??=25.5
??=101.3
??=???

XML Files

Structured data with schemas:

xml

<Tags>
  <Tag Name="Temperature" Value="25.5"/>
  <Tag Name="Pressure" Value="101.3"/>
  <Tag Name="Status" Value="Running"/>
</Tags>

File Path Configuration

Static Path

C:\Recipes\Recipe001.txt
\\Server\Share\Config.xml

Dynamic with Tags

C:\Recipes\Recipe{{Tag.RecipeNumber}}.txt
C:\Data\{{Tag.Year}}\{{Tag.Month}}\Data.csv
\\Server\{{Tag.Department}}\Settings.xml

Using Macros

{{ExecutionPath}}\Recipes\Current.txt
{{SolutionPath}}\Data\Config.xml

XML Schema Types

Tag List XML

Simple name-value pairs:

xml

<TagList>
  <Tag Name="Tank1_Level" Value="75.5"/>
  <Tag Name="Tank1_Temp" Value="22.3"/>
  <Tag Name="Pump1_Status" Value="1"/>
</TagList>

Tag Object XML

Complete tag hierarchy:

xml

<TagTree>
  <Folder Name="TankFarm">
    <Folder Name="Tank1">
      <Tag Name="Level" Value="75.5" Type="Double"/>
      <Tag Name="Temp" Value="22.3" Type="Double"/>
    </Folder>
  </Folder>
</TagTree>

Object Mapping

Configuration

1. Click Objects ellipsis (...)
2. Select tags to include:
   • Check individual tags
   • Select entire folders
   • Use search filter

Mapping Behavior

• Read: File values → Tags
• Write: Tags → File values
• Automatic type conversion
• Preserves tag structure

Execution Methods

Reading Files

csharp

// Load recipe file
@Dataset.File.Recipe001.Load();

// Check if successful
if (@Dataset.File.Recipe001.Status == "OK")
{
    // Tags now contain file values
    double temp = @Tag.Temperature;
}

Writing Files

csharp

// Set tag values
@Tag.Temperature = 25.5;
@Tag.Pressure = 101.3;
@Tag.Status = "Running";

// Save to file
@Dataset.File.Recipe001.Save();

Dynamic File Operations

csharp

// Change filename at runtime
@Tag.RecipeNumber = 5;
@Dataset.File.RecipeFile.FileName = 
    string.Format(@"C:\Recipes\Recipe{0}.txt", @Tag.RecipeNumber);

// Load specific recipe
@Dataset.File.RecipeFile.Load();

Recipe Management Example

Recipe Structure

# Recipe_001.txt
ProductCode=WIDGET-A
Temperature=185.5
Pressure=25.0
MixTime=300
Speed=1500

Load Recipe

csharp

public void LoadRecipe(int recipeNumber)
{
    // Set dynamic filename
    @Tag.CurrentRecipe = recipeNumber;
    
    // Load file
    @Dataset.File.RecipeFile.Load();
    
    // Verify loading
    if (@Dataset.File.RecipeFile.Status == "OK")
    {
        @Tag.RecipeLoaded = true;
        @Display.MessageBox("Recipe loaded successfully");
    }
}

Save Recipe

csharp

public void SaveRecipe()
{
    // Current values saved to file
    @Dataset.File.RecipeFile.Save();
    
    // Create backup
    string backup = string.Format(
        @"C:\Recipes\Backup\Recipe_{0}.txt",
        DateTime.Now.ToString("yyyyMMdd_HHmmss")
    );
    
    File.Copy(@Dataset.File.RecipeFile.FileName, backup);
}

Configuration Exchange

Export Settings

csharp

// Export current configuration
@Dataset.File.ConfigExport.FileType = "XML";
@Dataset.File.ConfigExport.XMLSchemaType = "TagObject";
@Dataset.File.ConfigExport.Save();

Import Settings

csharp

// Import from external system
@Dataset.File.ConfigImport.Load();

// Apply imported values
if (@Dataset.File.ConfigImport.Status == "OK")
{
    // Values automatically mapped to tags
    ApplyConfiguration();
}

Enabling Dataset Files

If Dataset Files menu is not visible:

1. Click Home icon
2. Under Solution Explorer Preferences
3. Set Filter to Show All Modules and Features

Alternative:

• Use Filter selector in sidebar
• Select appropriate visibility level

Best Practices Checklist 

•  Use absolute paths - Avoid relative paths in production
•  Validate data - Check values after loading
•  Handle errors - Check Status property
•  Backup files - Before overwriting
•  Use appropriate format - XML for structure, TXT for simple
•  Document mappings - Clear tag-to-file relationships
•  Test thoroughly - All file operations

Error Handling

csharp

try
{
    @Dataset.File.MyFile.Load();
    
    if (@Dataset.File.MyFile.Status != "OK")
    {
        string error = @Dataset.File.MyFile.ErrorMessage;
        LogError(error);
    }
}
catch (Exception ex)
{
    // Handle file system errors
    @Tag.FileError = ex.Message;
}

Troubleshooting

File not found:

• Verify path exists
• Check tag values in dynamic paths
• Confirm permissions
• Review network access

Load/Save fails:

• Check file format matches FileType
• Verify file not locked
• Confirm write permissions
• Review tag mappings

Data corruption:

• Validate file encoding
• Check decimal separators
• Verify date formats
• Review special characters

Missing menu option:

• Change Solution Explorer filter
• Enable all modules and features
• Restart Designer if needed

In this section...

Configuring DatasetFiles

To create and configure a DatabaseFile follow these steps:

1. Access Datasets / Files.
2. Click the plus icon.

3. Enter a Name and Description for the new File.

4. Click Ok.

The new DatasetFile object will show up in the DataGrid. To edit any property of the new DatasetFile, double-click the property you wish to edit on the corresponding row. The table below describes each available property you can configure for your DatasetFiles.

Column

Description

Name

The DatasetFile object's name. The system will warn you in case you choose an invalid name.

FileName

Specify the full path to the File. The file path can have Tag values embedded using curly bracket syntax. For example ExampleFile{{tag.Test}}.txt. 

When executing, the area in curly brackets is replaced by the Tag's value.

FileType

Specify the file type. The following options are available:

• Unicode
• ASCII
• XML

Objects

Click the button with three dots (...) to select the tags that you want to populate with data from the file with data from specific columns.

Description

The description for the File. Provide a meaningful description to make it easier to execute maintenance in the future.

XMLSchemaType

Represents the schema type of an XML file, which can be:

• A Tag List XML contains a tag list with the Tag name and value.
• A Tag Object XML that includes the entire tag tree and its children.

Enabling DatasetFiles on the Solution Explorer

You do not need to worry if you do not find the menu Dataset Files option under Dataset. The DatasetFile option may not appear due to a Filter option in the platform, which shows only the mostly commonly used features.

To change, follow the steps below:

Alternatively, you can change the Filter option by using the Filter selector on the sidebar, as shown in the image below: