Peter + AI

Posted on Sep 26

Understanding Uniface xmlsave: Exporting Data to XML Streams 🚀

#data #softwaredevelopment #tutorial

⚡ This blog post was created with AI assistance to help developers understand Uniface XML processing.

What is xmlsave? 🤔

The xmlsave statement in Uniface 10.4 is a powerful command that exports your component data into XML streams. Think of it as a data serializer - it takes your application data and converts it into a structured XML format that can be shared, stored, or transmitted.

In other programming languages, this concept is similar to:

C#: XmlSerializer.Serialize() 📊
Java: JAXB marshalling with @XmlRootElement ☕
Python: xml.etree.ElementTree or xmltodict 🐍
JavaScript: Converting objects to XML using libraries like xmlbuilder 🌐

Basic Syntax 📝

The basic syntax looks like this:

xmlsave XmlTarget, DTDname {, DTDmapping}

Let's break down what each part means:

XmlTarget: Where your XML data goes (like a variable or field) 🎯
DTDname: The Document Type Definition that defines your XML structure 📋
DTDmapping: Optional mapping between your data fields and XML elements 🗺️

Powerful Qualifiers (Options) ⚙️

Uniface xmlsave comes with several qualifiers that control how your data is exported:

/mod - Modified Data Only 🔄

Only includes data that has been changed. This is similar to dirty tracking in Entity Framework (C#) or change detection in Angular (JavaScript).

/one - Single Record 1️⃣

Exports only the current record with all its related data. Think of it like selecting a single entity with all its navigation properties in LINQ (C#).

/dtd and /ref - DTD Handling 📄

/dtd: Includes the DTD definition directly in the XML
/ref: Only includes a reference to the DTD location

/root - No XML Declaration 🚫

Excludes the XML version declaration (<?xml version="1.0"?>) from the output.

Real-World Example 💡

Here's a practical example of how you might use xmlsave in a Uniface operation:

operation XMLOUT
; This operation saves data to XML
params
 xmlstream [DTD:ABCDTD.ABC] MYSTREAM : OUT
endparams
clear
retrieve
xmlsave MYSTREAM, "DTD:ABCDTD.ABC"

This is equivalent to something like this in C#:

public string ExportToXml()
{
    var data = GetComponentData();
    var serializer = new XmlSerializer(typeof(MyDataClass));
    using (var writer = new StringWriter())
    {
        serializer.Serialize(writer, data);
        return writer.ToString();
    }
}

Understanding Return Values 📊

Uniface uses the $status variable to tell you what happened:

< 0: Something went wrong (error occurred) ❌
0: Perfect! XML created successfully ✅
> 0: XML created but some fields/entities weren't found ⚠️

This is similar to HTTP status codes or exception handling in modern programming languages.

Data State Tracking 📈

One unique feature of Uniface xmlsave is its sophisticated state tracking. It automatically adds XML attributes to track:

"est": Established (existing) records 🏠
"mod": Modified records ✏️
"new": Brand new records ✨
"del": Deleted records 🗑️

This is more sophisticated than typical serialization in other languages, which usually don't track data state automatically.

Event Triggers (Hooks) 🎣

Uniface fires special triggers during the xmlsave process:

preSerialize: Runs before each record is saved
postSerialize: Runs after each record is saved

This is similar to:

C#: Event handlers or Entity Framework interceptors
JavaScript: Middleware functions in Express.js
Java: Listeners or interceptors in Spring Framework

Important Terms Explained 📚

DTD (Document Type Definition): A blueprint that defines what elements and structure your XML can have
Component: In Uniface, this is like a form or screen that contains your data
Occurrence: A single record or row of data
Hitlist: The collection of all records currently loaded in your component
Entity: Similar to a database table or class in object-oriented programming

Best Practices 🌟

Use store/complete before xmlsave: This prevents empty records in your XML output
Handle errors properly: Always check $status and $procerror
Choose the right qualifiers: Use /mod for incremental updates, /one for single records
Test your DTD mapping: Make sure all your fields are properly mapped

Common Pitfalls to Avoid ⚠️

Truncated hitlists: Using store without /complete can cause issues
Missing field mappings: Unmapped fields won't appear in your XML
DTD validation errors: Make sure your DTD syntax is correct

Conclusion 🎯

Uniface's xmlsave statement provides a robust way to export data to XML with advanced features like automatic state tracking and event hooks. While it might seem complex compared to simple JSON serialization in modern languages, it offers powerful capabilities for enterprise applications that need detailed data lineage and state management.

Whether you're migrating from Uniface or working with legacy systems, understanding xmlsave helps you appreciate the sophisticated data handling capabilities that were built into enterprise development platforms.

Happy coding! 🚀✨

DEV Community