|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Document Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.Free
Frees a JSON document handle.
Intention
The PSJ.Free command in SPR releases all resources tied to a JSON document handle ($$DOC) that was previously created by commands like PSJ.CreateArrFromStr or PSJ.CreateObjPairs. It’s like telling your robot to shred a JSON file and clear its memory slot after you’re done with it, preventing memory leaks in your script.
For example, after creating a JSON array with PSJ.CreateArrFromStr, you must use PSJ.Free to clean up the handle when it’s no longer needed.
Illustration
📝 Free: PSJ.Free|$$DOC releases the handle $$DOC.
Syntax
PSJ.Free|$$DOC
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The handle of the JSON document to free (e.g., $$DOC as a number from PSJ.CreateArrFromStr). Required.
Technical Background
This command calls W_JSON_FreeHandle, which frees all nodes associated with a JSON document identified by docHandle. It returns 0 on success or 1 if the handle is invalid. The function validates the handle, uses Node_FreeSubtree to release all nodes, resets the document’s root node, and marks it unused. If the handle is invalid, it updates gLastJSONError and gLastJSONErrorMsg. This is critical to prevent memory leaks after creating JSON structures.
Examples
'***********************************
' Sample 1: Free After Array Creation
PSJ.CreateArrFromStr|a;b;c|;|$$DOC
' Use the array
PRT.Handle: $$DOC
' Free the handle
PSJ.Free|$$DOC
MBX.Ready
'***********************************
' Sample 2: Free After Object Creation
PSJ.CreateObjPairs|key=val|$$OBJ
' Use the object
PRT.Handle: $$OBJ
' Free the handle
PSJ.Free|$$OBJ
MBX.Ready
Remarks
- Essential for cleaning up after creating JSON documents.
- No return value in SPR; errors are logged internally.
- Use PSJ.ErrCode to check if freeing failed (e.g., invalid handle).
Limitations
- $$DOC must be a valid handle from a prior JSON creation command.
- Double-freeing a handle or using an invalid handle may cause undefined behavior.
See also: