Since the 2023R2 release, Sage X3 has introduced JSON parsing 4GL functions, enabling developers to efficiently fetch and process data from JSON-formatted strings. This blog explores the key JSON parsing functions—ParseInstance, Contains$, and Select$—and provides practical examples and best practices for their use.
Introduction to JSON Parsing in Sage X3
JSON (JavaScript Object Notation) is a lightweight data-interchange format widely used for structured data. With Sage X3’s JSON parsing functions, you can parse JSON strings, check for specific properties, and extract values seamlessly within 4GL scripts. These functions are particularly useful for integrating external data or processing structured inputs.
New Stuff :- Implementing User-Specific Access Control in Sage X3 for the Receipt Line Inquiry Screen
Key JSON Parsing Functions
1.ParseInstance
The ParseInstance function is used to parse a JSON string into an object that can be queried or manipulated.
Syntax:
ParseInstance OBJECT With JSON_OBJECT
- OBJECT: The object used to parse the input JSON.
- JSON_OBJECT: The JSON string to be parsed (recommended to use Clbfile).
Example:
# Procedure to parse a JSON object
Local Clbfile SRCJSON
SRCJSON = '{"msg":"Hello World!"}'
# Create the object
Local Instance OBJ Using OBJECT
# Parse the object
ParseInstance OBJ With SRCJSON
# Free memory
FreeGroup OBJ
This code parses a simple JSON string {“msg”:”Hello World!”} into the OBJ instance for further processing.
2.Contains$
The Contains$ function checks if a parsed JSON object contains a specific property, returning 1 if the property exists and 0 if it does not.
Syntax:
RETURN_VALUE = JSON_OBJECT.Contains$(JSON_POINTER)
- RETURN_VALUE: Integer (1 for exists, 0 for does not exist).
- JSON_OBJECT: The parsed JSON object.
- JSON_POINTER: The JSON pointer expression to check (use square brackets for array indices).
Example:
# Procedure to check properties
Local Clbfile SRCJSON
SRCJSON = '{"msg":"Hello World!", "list" : ["one", "two", "three"]}'
# Create the object
Local Instance OBJ Using OBJECT
# Parse the object
ParseInstance OBJ With SRCJSON
# Check if the JSON contains a property
Local Integer R
R = OBJ.Contains$("/msg") # Returns 1
# Check array element
R = OBJ.Contains$("/list[1]") # Returns 1
# Free memory
FreeGroup OBJ
This example checks for the msg property and the second element in the list array.
3.Select$
The Select$ function retrieves the value of a specific property from a parsed JSON object.
Syntax:
RETURN_VALUE = JSON_OBJECT.Select$(JSON_PATH)
- RETURN_VALUE: String containing the selected property’s value.
- JSON_OBJECT: The parsed JSON object.
- JSON_PATH: The JSON path expression to select (use square brackets for array indices).
Example:
Procedure to select properties
# Procedure to select properties
Local Clbfile SRCJSON
SRCJSON = '{"msg":"Hello World!", "list" : ["one", "two", "three"]}'
# Create the object
Local Instance OBJ Using OBJECT
# Parse the object
ParseInstance OBJ With SRCJSON
# Select a property
Local Char MYSTR(30)
MYSTR = OBJ.Select$("$.msg") # Returns "Hello World!"
# Select array element
MYSTR = OBJ.Select$("$.list[1]") # Returns "two"
# Free memory
FreeGroup OBJ
This code extracts the msg property and the second element of the list array.
Best Practices for JSON Parsing
- To handle JSON data efficiently, especially when dealing with arrays or dynamic data, follow these best practices:
- Use Clbfile for JSON Strings: Store JSON strings in Clbfile variables to handle large or complex JSON data effectively.
- Always Free Memory: Use FreeGroup to release memory allocated to the JSON object and prevent memory leaks.
- Iterate Arrays with Loops: For JSON arrays, use a WHILE loop with Contains$ to dynamically check and extract elements.
Example (Iterating an Array):
# Sample JSON
Local Clbfile SRCJSON
SRCJSON = '{"msg":"Hello World!", "list" : ["one", "two", "three"]}'
# Create the object
Local Instance OBJ Using OBJECT
# Parse the object
ParseInstance OBJ With SRCJSON
# Array to store results
Local Char MYSTR(30)(0..)
Local Integer I : I = 0
# Iterate over list array
WHILE I >= 0
# Check if the property exists
If OBJ.Contains$("/list/" + NUM$(I)) = 1
MYSTR(I) = OBJ.Select$("$.list[" + NUM$(I) + "]")
I += 1
Else
BREAK
Endif
WEND
# Free memory
FreeGroup OBJ
This script iterates through the list array, extracting each element until no more elements are found.
Conclusion
Sage X3’s JSON parsing 4GL functions (ParseInstance, Contains$, and Select$) provide a robust way to handle JSON data within your scripts. By following the syntax and best practices outlined above, you can efficiently parse, query, and extract data from JSON strings. Always ensure proper memory management with FreeGroup and use loops for dynamic array processing to make your code scalable and maintainable.