🔄 Converting Structs to JSON in Uniface 10.4: The structToJson Statement Explained

🤖 This blog post was created with AI assistance to provide comprehensive technical guidance based on official Uniface 10.4 documentation.

The structToJson statement in Uniface 10.4 is a powerful ProcScript function that converts complex data structures (Structs) into JSON format 📊. This functionality is essential for modern web applications, API integrations, and data exchange between different systems.

📝 Basic Syntax and Usage

The basic syntax for structToJson is straightforward:

structToJson {/bmp} {/whitespace} JsonTarget, StructSource

Parameters explained:

• JsonTarget: A string variable, parameter, or field that will hold the resulting JSON text 📄
• StructSource: The Struct variable or parameter containing the data to be converted 🗂️

🎯 Practical Example

Here's a complete example showing how to use structToJson:

variables
    vStruct : struct
    vJsonOutput : string
endvariables

; Create a sample struct
vStruct->name = "John Developer"
vStruct->age = 30
vStruct->skills->{1} = "C#"
vStruct->skills->{2} = "Uniface"
vStruct->skills->{3} = "SQL"
vStruct->active = "T"

; Convert struct to JSON
structToJson /whitespace vJsonOutput, vStruct

; Output the result
putmess vJsonOutput

This example creates a Struct with personal information and converts it to readable JSON format 🎨.

🔧 Qualifiers: Controlling Output Format

The structToJson statement supports two important qualifiers:

/whitespace Qualifier

The /whitespace qualifier formats the JSON with indentation and line breaks for better readability 📖:

; Without /whitespace:
{"name":"John","skills":["C#","Uniface"]}

; With /whitespace:
{
 "name" : "John",
 "skills" : 
 [
  "C#",
  "Uniface"
 ]
}

/bmp Qualifier

The /bmp qualifier ensures that Unicode characters outside the Basic Multilingual Plane (BMP) are properly escaped 🌐. This is important for compatibility with systems that only support UCS-2 encoding.

📊 Understanding JSON Structure Types

The structToJson function can generate two main JSON structure types:

JSON Objects

When all Struct members have names, they are converted to JSON objects using curly braces {} 🏗️:

; Struct with named members
vPerson->firstName = "Maria"
vPerson->lastName = "Schmidt"

; Results in JSON object:
{
 "firstName" : "Maria",
 "lastName" : "Schmidt"
}

JSON Arrays

When Struct members don't have names or are indexed, they become JSON arrays using square brackets [] 📋:

; Struct with indexed members
vSkills->{1} = "JavaScript"
vSkills->{2} = "Python"
vSkills->{3} = "Go"

; Results in JSON array:
["JavaScript", "Python", "Go"]

⚠️ Error Handling and Status Codes

Proper error handling is crucial when using structToJson. The function returns different status codes:

structToJson vJsonOutput, vStruct

if ($status = 0)
    putmess "✅ Conversion successful!"
    ; Use filedump to save to file if needed
    filedump "output.json", vJsonOutput
else
    putmess "❌ Conversion failed: " ; $procerror
endif

Common status codes:

• 0: Successful conversion ✅
• < 0: Conversion failed - check $procerror for details ❌

Typical errors include:

• -1905 (STRUCTERR_INPUT): Invalid input struct data 🚫

🎨 Advanced Features and Annotations

Uniface automatically handles various data types and applies appropriate JSON formatting:

Data Type Mapping

• Strings: Enclosed in double quotes with proper escaping 📝
• Numbers: Written as numeric values without quotes 🔢
• Booleans: Converted to JSON true/false values ✔️
• Special Characters: Properly escaped (quotes, backslashes, GOLD characters) 🔐

Struct Annotations

You can use $tags to set jsonClass annotations that control how Structs are converted:

• object: Forces conversion to JSON object 🏗️
• array: Forces conversion to JSON array 📋
• value: Treats as simple value 💎

💾 Working with Files

To save JSON output to a file, use the filedump statement:

structToJson vJsonOutput, vStruct

if ($status = 0)
    ; Save to local file
    filedump "data.json", vJsonOutput

    ; Or save to server path  
    lfiledump "/path/to/server/data.json", vJsonOutput
endif

🌟 Best Practices

1. Always implement error handling: Check $status after each conversion 🛡️
2. Use meaningful variable names: Makes code more maintainable 📖
3. Consider output format: Use /whitespace for debugging, omit for production 🎯
4. Test complex structures: Verify nested objects and arrays work as expected 🧪
5. Handle Unicode properly: Use /bmp when needed for compatibility 🌐
6. Document your Struct structure: Comment complex data transformations 📚

🔗 Integration with Other Uniface Features

The structToJson function works seamlessly with other Uniface data transformation features:

• componentToStruct: Convert form data to Struct, then to JSON 🔄
• xmlToStruct: Transform XML data via Struct to JSON 📄
• jsonToStruct: Round-trip conversion for data processing 🔁

🎯 Real-World Use Cases

API Integration: Convert Uniface form data to JSON for REST API calls 🌐

Data Export: Export database records as JSON for external systems 📤

Configuration Files: Generate JSON configuration from Uniface parameters ⚙️

Web Applications: Send structured data to JavaScript front-ends 💻

🏁 Conclusion

The structToJson statement in Uniface 10.4 is an essential tool for modern application development 🚀. It provides:

• Simple syntax for quick implementation ⚡
• Flexible output formatting options 🎨
• Robust error handling for production use 🛡️
• Seamless integration with Uniface development workflow 🔗

Whether you're building web APIs, integrating with external systems, or processing complex data structures, structToJson makes working with JSON data in Uniface straightforward and reliable 💪.

Have you used structToJson in your Uniface projects? Share your experiences and tips in the comments below! 💬

🤖 Transparency Note: This blog post was created with AI assistance based on official Uniface 10.4 documentation to provide accurate and comprehensive technical guidance.