|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Value Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.SetNull
Sets or creates a null value at a specified path in a JSON object.
Intention
The PSJ.SetNull command in SPR modifies a JSON document ($$DHA) by setting a null value at a specified path ($$PTH), creating intermediate objects if needed. It returns a status code (non-zero for success, 0 for failure), which you can optionally store in a variable (e.g., $$RET). This is useful for adding or updating null values in JSON data.
Think of it as telling your robot, “Put a null value at this spot in the JSON, and build the path if it’s not there,”—and it replies with a number like 1 for success, either on the Top of Stack (TOS) or in your variable.
Illustration
Consider an empty JSON document:
{}
- 🔍 PSJ.SetNull|$$DHA|person.address.optionalField|$$RET creates "person.address.optionalField" as null, resulting in {"person": {"address": {"optionalField": null}}}, and stores "1" (success) in $$RET.
- 🔍 PSJ.SetNull|$$DHA|person.name adds "person.name": null, placing "1" on TOS.
Syntax
PSJ.SetNull|$$DHA|$$PTH[|$$RET]
Parameter Explanation
P1 - $$DHA - (Variable, Numeric)
The handle to the JSON document (e.g., $$DHA as "1"). Required. Obtained from PSJ.Parse.
P2 - $$PTH - (Variable, String)
The dot-separated path where the null value should be set (e.g., $$PTH as "person.address.optionalField"). Required.
P3 - $$RET - (Variable, String, Optional)
The variable to store the status code (e.g., $$RET). If omitted, the result is returned on Top of Stack (TOS). Non-zero indicates success, 0 indicates failure.
Examples
'***********************************
' PSJ.SetNull - Sample 1: Create Path
'***********************************
PSJ.Parse|{}|$$DHA
PSJ.SetNull|$$DHA|person.address.optionalField|$$RET
MBX.Status: $$RET ' Displays "1" (success)
PSJ.NodeToStr|0|0|0|$$JSON ' Get full document
PRT.JSON: $$JSON ' Prints {"person":{"address":{"optionalField":null}}}
PSJ.Free|$$DHA
'
'***********************************
' PSJ.SetNull - Sample 2: Overwrite Existing
'***********************************
PSJ.Parse|{"data": {"value": 42}}|$$DHA
PSJ.SetNull|$$DHA|data.value|$$RET
PRT.Status: $$RET ' Prints "1" (success)
PSJ.NodeToStr|0|0|0|$$JSON
MBX.JSON: $$JSON ' Displays {"data":{"value":null}}
PSJ.Free|$$DHA
'
'***********************************
' PSJ.SetNull - Sample 3: Status on TOS
'***********************************
PSJ.Parse|{}|$$DHA
PSJ.SetNull|$$DHA|test
' Places "1" (success) on TOS
PSJ.Free|$$DHA
'
Remarks
- Returns a status code as a string: non-zero (e.g., "1") for success, "0" for failure.
- Creates intermediate objects if the path doesn’t exist (e.g., "person.address" becomes {"person": {"address": {}}}).
- Overwrites existing non-array values at the final key with null.
- Sets the node type to %JSON_TYPE_NULL and value to "" internally.
Limitations
- Fails (returns "0") if $$DHA is invalid or if the path targets an array element (e.g., "arr[0]").
- Does not support array index notation in $$PTH; use PSJ.SetVal for arrays.
- Error details require separate calls to W_JSON_GetLastErrorMsg (not directly accessible in SPR).
See also: