🚀 Converting XML to Structs in Uniface 10.4: The xmlToStruct Statement Explained

Note: This blog post was created with AI assistance and is based on the official Uniface 10.4 documentation.

Working with XML data in Uniface applications? The xmlToStruct statement is your go-to solution for converting XML documents into Uniface Structs, making data manipulation much easier! 📊

🎯 What is xmlToStruct?

The xmlToStruct statement transforms XML documents into Structs - a structured data format that Uniface can work with efficiently. Think of it as converting a complex XML file into an organized data structure that your ProcScript code can easily access and manipulate.

Struct: A hierarchical data structure in Uniface that can contain multiple data types and nested elements, similar to objects in other programming languages.

📝 Basic Syntax

The xmlToStruct statement has two main formats:

xmlToStruct {/full} {/whitespace} StructTarget, XmlDocument

xmlToStruct {/full} {/validate} {/schema} StructTarget, XmlDocument, SchemaList

🔧 Parameters Explained

• StructTarget: The variable that will hold your converted data (must be of type struct or any)
• XmlDocument: Your XML source - can be a string, file name, or URL
• SchemaList: Optional schema information for validation

⚡ Key Qualifiers

Qualifiers are special switches that change how the conversion works:

🔍 /full

Includes everything from your XML - comments, DOCTYPE declarations, and namespace information. Use this when you need to recreate the exact XML later.

📏 /whitespace

Preserves whitespace (spaces, tabs, line breaks) between elements. Normally, Uniface strips unnecessary whitespace to keep things clean.

✅ /validate

Checks if your XML follows its DTD (Document Type Definition) or schema rules. This ensures your XML is not just well-formed but also valid according to its specification.

📋 /schema

Includes schema information and automatically enables validation. This also converts data types correctly (dates become dates, numbers become numbers, etc.)

💡 Practical Example

Let's see xmlToStruct in action! Here's how to convert a simple XML document:

; Define our variables
variables
  vStruct : struct
  vXmlContent : string
endvariables

; Sample XML content
vXmlContent = "<?xml version='1.0' encoding='UTF-8'?><movie>The Matrix</movie>"

; Convert XML to Struct
xmlToStruct vStruct, vXmlContent

; The result will be:
; []
;  [movie] = "The Matrix"

🎯 Understanding the Result Structure

Every converted XML creates a nameless root Struct that represents the entire document. The actual XML root element becomes the first named child of this root. This design allows Uniface to handle XML declarations and other document-level constructs.

🔍 Viewing Your Struct

Use $dbgString to see exactly what your Struct contains:

; Convert and display the structure
xmlToStruct/full vStruct, vXmlContent
vOutput = "%%vStruct->$dbgString%%"

📊 Data Type Conversion with Schema

When you use /schema, xmlToStruct automatically converts XML data types to appropriate Uniface types:

XML Type	Uniface Type	Example
string, token, name	string	"Hello World"
date, time, dateTime	date, time, datetime	2024-12-25
integer, decimal	numeric	42, 3.14
boolean	boolean	T or F
base64Binary	raw	Binary data

⚠️ Error Handling

Always check the $status variable after calling xmlToStruct:

xmlToStruct vStruct, vXmlFile

; Check if conversion was successful
if ($status = 0)
  ; Success! Process your struct
  message "XML converted successfully! 🎉"
else
  ; Handle errors
  message "Conversion failed. Error: %%$procerror%%"
endif

🚨 Common Error Codes

• -4: File doesn't exist or can't be opened
• -1503: XML is not well-formed (syntax errors)
• -1504: XML doesn't conform to its DTD/schema

🏆 Best Practices

• Always validate input: Use /validate for production code to catch malformed XML early 🛡️
• Check $status: Never assume conversion succeeded without checking
• Use /schema for typed data: Let Uniface handle data type conversion automatically
• Handle large files carefully: XML conversion loads everything into memory
• Use /full sparingly: Only when you need to preserve exact XML structure

🔄 Working with Complex XML

For XML with multiple namespaces, use the SchemaList parameter:

; Define schema locations
vSchemaList = ""
putitem/id vSchemaList, "NAMESPACE", "http://example.com/orders"
putitem/id vSchemaList, "LOCATION", "orders.xsd"

; Convert with schema validation
xmlToStruct/schema vStruct, vXmlFile, vSchemaList

🎯 Key Takeaways

• xmlToStruct converts XML documents into Uniface Structs for easy data manipulation
• Use qualifiers like /validate and /schema for robust data processing
• Always check $status for error handling
• The result always has a nameless root containing your XML root element
• Schema-aware conversion provides automatic data type mapping

🚀 Ready to Convert?

The xmlToStruct statement is a powerful tool for XML processing in Uniface 10.4. Whether you're working with web services, configuration files, or data exchange formats, understanding this statement will make your XML handling much more efficient! 💪

Have you used xmlToStruct in your projects? Share your experiences and tips in the comments below! 👇

Happy coding! 🎉

Keywords: uniface xmltostruct xml conversion procscript