|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Utility and Conversion > PSJ. - JSON Operations |
SPR Script Language
PSJ.Repair
Checks for orphaned nodes in the global JSON structure and optionally removes them.
Intention
The PSJ.Repair command scans the entire internal JSON node structure managed by the JSW library, looking for "orphaned" nodes. An orphan is a node that exists but is not referenced as a child by its designated parent node, nor is it the root node of any active document. This situation might occur due to internal errors or incomplete operations. The command can optionally remove these orphaned nodes and their subtrees, freeing up memory. Note that the check for duplicate keys, previously part of repair operations, is now inherently handled by the WsLnTre B-Tree structure used for Objects and is not performed by this command.
Illustration
📝 Check for orphans without removing:
PSJ.Repair|0|$$RES
(Scans for orphans; $$RES will be 0 if check completes successfully. Check PSJ.ErrMsg for orphan count info.)
📝 Check for orphans and remove them:
PSJ.Repair|1|$$RES
(Scans for orphans and calls W_JSON_Node_FreeSubtree on any found. $$RES will be 0 if check/removal completes.)
Syntax
PSJ.Repair[|$$RMO[|$$RES]]
Parameter Explanation
P1 - $$RMO - (Variable, Numeric, Optional)
Flag indicating whether to remove found orphaned nodes.
- 0 (Default): Only check for orphans, do not remove.
- 1: Check for and remove (FreeSubtree) any orphans found.
(Any non-zero value is treated as 1). If omitted, defaults to 0.
P2 - $$RES - (Variable, Numeric, Optional)
The variable where the result code (%JSON_ERR_*) will be stored. 0 indicates the repair check completed without internal errors (it does not indicate whether orphans were found). Non-zero indicates an error during the check itself. If omitted, the result code is returned but not stored.
Technical Background
This command calls the W_JSON_Repair(removeOrphans?, %TRUE) function in the JSW library (the second parameter, for removing duplicate keys, is ignored as it's handled by WsLnTre). The JSW function then calls the internal helper W_JSON_Repair_CheckOrphanedNodes(removeOrphans?). This helper iterates through all nodes (1 to gNodeCount). For each active node, it checks if it's a root node of any document. If not, it checks if its parent (gNodeParent) is valid and active. If the parent is valid, it checks if the current node exists in the parent's children (using W_JSON_Node_GetChildIDs for arrays or WsLnTre iteration for objects). If the node is not linked correctly, it's considered an orphan. If the `removeOrphans` flag is true, W_JSON_Node_FreeSubtree is called on the orphan. The command returns %JSON_ERR_NONE on successful completion of the check/repair process, or an error code if the process itself failed.
Examples
'***********************************
' Sample: Check and remove orphans after complex operations
' ... perform various JSON modifications ...
PSJ.Repair|1|$$REP_STAT ' Check and remove orphans
IFE $$REP_STAT=0 THEN
PSJ.ErrMsg|$$REP_MSG ' Get status message (includes orphan count)
PRT.Repair Check/Remove Complete: $$REP_MSG
ELSE
PRT.Error during Repair: $$REP_STAT
END
MBX.Ready
'***********************************
Remarks
- The number of orphans found/removed is typically reported in the success message retrieved via PSJ.ErrMsg after a successful repair run (Return Code 0).
- Running Repair can be useful after complex manipulations or if errors occurred that might have left detached nodes, but it can be a potentially slow operation on very large structures.
- Duplicate key removal is no longer relevant due to WsLnTre handling.
Limitations
- The check involves iterating through all nodes and potentially parent children, which can impact performance.
See also: