|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Value Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.GetNull
Checks if the JSON node at a specified path is of type NULL.
Intention
Use the PSJ.GetNull command to determine if the value associated with a specific $$PATH in a JSON document ($$DOC) is explicitly the JSON null type. It returns 1 if the node exists and is null, and 0 otherwise (if the node doesn't exist, isn't null, or an error occurs). This is useful for checking optional fields or explicitly null values.
Illustration
📝 JSON: {"a": null, "b": 123}
PSJ.Parse|'{"a": null, "b": 123}'|$$DOC
PSJ.GetNull|$$DOC|a|$$IS_NULL_A // $$IS_NULL_A becomes 1
PSJ.GetNull|$$DOC|b|$$IS_NULL_B // $$IS_NULL_B becomes 0
PSJ.GetNull|$$DOC|c|$$IS_NULL_C // $$IS_NULL_C becomes 0 (path not found)
Syntax
PSJ.GetNull|$$DOC|$$PATH[|$$RET_CODE]
Parameter Explanation
P1 - $$DOC - (Variable, Numeric)
The identifier of the JSON document handle. Required.
P2 - $$PATH - (Variable, String)
The Universal Path (Dot-Notation or JSON Pointer) to the node to check. Assumed UTF-8, converted internally. Required.
P3 - $$RET_CODE - (Variable, Numeric, Optional)
The variable where the result code will be stored.
- 1: The node at the path exists and is type NULL.
- 0: The node was not found, or it exists but is not type NULL, or an error occurred during path traversal.
If omitted, the result is returned but not stored.
Technical Background
This command calls the W_JSON_GetNullByPath(docHandle, pathW) function in the JSW library after converting the $$PATH parameter to a WSTRING. The underlying function first uses W_JSON_FindNodeByPath to locate the node. If found, it checks if gNodeType(NodeID) equals %JSON_TYPE_NULL. It returns %TRUE (1) only if the node is found AND its type is NULL. Otherwise, it returns %FALSE (0) without setting an error specifically for type mismatch, allowing for simpler conditional checks.
Examples
'***********************************
' Sample: Check if a field is null
PSJ.Parse|'{"optionalField": null, "requiredField": "value"}'|$$DOC
PSJ.GetNull|$$DOC|optionalField|$$IS_OPT_NULL
PSJ.GetNull|$$DOC|requiredField|$$IS_REQ_NULL
PSJ.GetNull|$$DOC|missingField|$$IS_MISS_NULL
PRT.Optional Null? $$IS_OPT_NULL ' Output: 1
PRT.Required Null? $$IS_REQ_NULL ' Output: 0
PRT.Missing Null? $$IS_MISS_NULL ' Output: 0
PSJ.Free|$$DOC
MBX.Ready
'***********************************
Remarks
- This command is useful for determining if a field exists and is explicitly set to null.
- It returns 0 if the path doesn't lead to a node or if the node exists but is not of type NULL.
- Check PSJ.ErrCode if you need to differentiate between "not found" and "found but not null" (though GetNull itself doesn't set a type mismatch error).
Limitations
- Relies on the validity of the document handle and the correctness of the path string.
See also: