|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Document Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.Validate
Performs basic validation checks on a JSON document handle and its root node.
Intention
Use the PSJ.Validate command to quickly check if a given document handle ($$DOC) is valid and refers to a properly structured initial document. Specifically, it verifies:
1. The handle is within the valid range.
2. The handle is marked as currently 'in use'.
3. The handle points to a valid root node ID.
4. The root node is active (not freed).
5. The root node's type is either Object or Array.
It returns 1 if all checks pass, and 0 otherwise, setting a specific error message indicating the reason for failure.
Illustration
📝 Validate a recently parsed document:
PSJ.Parse|'{"ok":true}'|$$DOC
PSJ.Validate|$$DOC|$$IS_VALID
Result: $$IS_VALID will be set to "1".
📝 Validate an invalid handle:
VAR $$BAD_HANDLE = 999
PSJ.Validate|$$BAD_HANDLE|$$IS_VALID_BAD
Result: $$IS_VALID_BAD will be set to "0", and PSJ.ErrMsg will indicate an out-of-range handle.
Syntax
PSJ.Validate|$$DOC[|$$RES]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The identifier of the JSON document handle to validate. Required.
P2 - $$RES - (Variable, Numeric, Optional)
The variable where the validation result code will be stored.
- 1: Validation checks passed.
- 0: Validation failed (check PSJ.ErrMsg for reason).
If omitted, the result code is returned but not stored.
Technical Background
This command calls the W_JSON_Validate(docHandle) function in the JSW library. The JSW function performs a series of checks against the global document management arrays (`gDocRoot`, `gDocInUse`) and node type array (`gNodeType`). It checks if the `docHandle` is within the bounds of `gDocRoot`, if `gDocInUse(docHandle)` is true, if `gDocRoot(docHandle)` points to a valid node index within `gNodeType`, and if the type of that node (`gNodeType(gDocRoot(docHandle))`) is either %JSON_TYPE_OBJECT or %JSON_TYPE_ARRAY. If any check fails, it calls `W_JSON_SetError` with an appropriate message and returns %FALSE (0); otherwise, it returns %TRUE (1).
Examples
'***********************************
' Sample: Validate handle after parsing
PSJ.Parse|'["Valid"]'|$$DOC
IFE $$DOC > 0 THEN
PSJ.Validate|$$DOC|$$IS_OK
IFE $$IS_OK = 1 THEN
PRT.Document handle $$DOC is valid.
ELSE
PSJ.ErrMsg|$$ERR
PRT.Validation failed for $$DOC: $$ERR
END
PSJ.Free|$$DOC
ELSE
PRT.Parsing failed.
END
MBX.Ready
'***********************************
Remarks
- This command performs only basic checks on the handle and root node. It does not validate the entire JSON structure for correctness or conformance beyond the root type.
- It's useful primarily after parsing or loading to ensure a valid starting point before performing further operations.
Limitations
- Does not guarantee the integrity of the entire document tree, only the handle and root node.
See also: