|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > JSON - Parser > Parser-Operations > !Value Operations > PSJ. - JSON Operations |
SPR Script Language
PSJ.GetStr
Retrieves the string value of a node at a specified path in a JSON document.
Intention
The PSJ.GetStr command in SPR retrieves the string value of a node at a specified path ($$PTH) within a JSON document identified by $$DCH). Optionally, it stores the result in a variable specified by $$RTN. This command is useful for extracting string data from a JSON structure, such as a text field or a converted value.
For example, retrieving the value at "user.name" from document 100 might return "John Doe" if that path points to a string node.
Illustration
📝 Get a String: PSJ.GetStr|100|user.name retrieves the string at "user.name" from document 100.
📝 With Return Variable: PSJ.GetStr|200|data.title|$$TIT stores the string at "data.title" in $$TIT.
Syntax
PSJ.GetStr|$$DCH|$$PTH[|$$RTN]
Parameter Explanation
P1 - $$DCH - (Variable, Numeric)
The identifier of the JSON document (e.g., $$DCH as "100"). Required.
P2 - $$PTH - (Variable, String)
The dot-separated path to the node in the JSON document (e.g., $$PTH as "user.name"). Required.
P3 - $$RTN - (Variable, String, Optional)
The variable to store the retrieved string value (e.g., $$RTN as "$$TIT"). If omitted, the string is returned but not stored in a variable.
Examples
'***********************************
' Sample 1: Retrieve a String
PSJ.GetStr|100|user.name
' Retrieves the string at "user.name" from document 100
MBX.Ready
'***********************************
' Sample 2: Retrieve and Store a String
PSJ.GetStr|200|data.title|$$TIT
' Stores the string at "data.title" in $$TIT
MBX.The title is: $$TIT
'***********************************
Remarks
- Handles various node types (strings, numbers, booleans, null); non-string types are converted to strings where possible.
- For arrays, the path must include a valid index (e.g., "array.0").
- Use PSJ.ErrCode to check for errors like invalid paths or unsupported node types.
Limitations
- $$DCH must be a valid document handle.
- $$PTH must resolve to an existing node; objects cannot be directly converted to strings.
- Returns an empty string if the path is not found or an error occurs.
See also: