PARSE JSON
operand1
[ENCODED[IN]
CODEPAGE
operand2]
|
||||||||||
|
|
INTO |
|
PATH operand3 |
[WITH SEPARATOR operand4]
|
[NAME operand5]
|
[VALUE operand6]
|
|
|
||
NAME operand5 |
[VALUE operand6]
|
|||||||||
VALUE
operand6 |
||||||||||
[ GIVING
operand7
[SUBCODE
operand8]]
|
||||||||||
| statement... | ||||||||||
END-PARSE
|
(structured mode only) | |||||||||
LOOP |
(reporting mode only) | |||||||||
This document covers the following topics:
For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.
Related Statement: REQUEST
DOCUMENT.
Belongs to Function Group: Internet and Parsing.
The PARSE JSON statement allows you to parse JSON documents from a Natural
program. See also Statements for Internet Access
and Parsing in the Programming Guide.
It is recommended that you use dynamic variables when using the PARSE JSON
statement, because it is not feasible to determine the length of a static variable. Using
static variables might result in the truncation of the value intended for the
variable.
For information on Unicode support, see PARSE
JSON in the Unicode and Code Page Support
documentation.
The markings below are used in path strings to represent the various data structures and their statuses in a JSON document:
| Marking | JSON Data | Location in Path String |
|---|---|---|
< |
Start of an Object | At the beginning, at the end, or between field names |
> |
End of an Object | At the end |
( |
Start of an Array | At the beginning, at the end, or between field names |
) |
End of an Array | At the end |
/ |
Separator
Note: |
|
$ |
Parsed data - character data string | At the end |
By using this additional markup in the path string, you can differentiate the elements of the JSON document in the output more easily.
The following Natural system variables are automatically created for each PARSE
JSON statement that is executed:
The notation
(r) after
*PARSE-TYPE, *PARSE-LEVEL,
and *PARSE-INDEX is used to indicate the label or statement
number of the statement in which the PARSE was issued. If
(r) is not specified, the corresponding
system variable represents the system variable of the JSON data currently processed in
the active PARSE processing loop.
For more information on these system variables, see the System Variables documentation.
Operand Definition Table:
| Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operand1
|
C | S | A | U | B | yes | no | |||||||||||||
operand2
|
C | S | A | yes | no | |||||||||||||||
operand3
|
S | A | U | B | yes | yes | ||||||||||||||
operand4
|
C | S | A | U | B | yes | no | |||||||||||||
operand5
|
S | A | U | B | yes | yes | ||||||||||||||
operand6
|
S | A | U | B | yes | yes | ||||||||||||||
operand7
|
S | I4 | yes | yes | ||||||||||||||||
operand8
|
S | I4 | yes | yes | ||||||||||||||||
Syntax Element Description:
| Syntax Element | Description |
|---|---|
operand1
|
JSON
Document: Operand1
represents the JSON document to be parsed. The JSON document might not be changed
while being parsed. If you try to change the JSON document during parsing, the
change does not take effect in the PARSE process.
|
ENCODED [IN] CODEPAGE operand2
|
ENCODED [IN] CODEPAGE:
|
PATH operand3
|
Path:
The Note: See also Example 1 - Using the PATH Option. |
SEPARATOR operand4
|
Separator:
|
NAME operand5 |
Data Element Name:
If See also Example 3 - Using the NAME Option. |
VALUE operand6 |
Data Element Content:
If there is no value, a given dynamic variable associated with it is set to
See also Example 4 - Using the VALUE Option. |
GIVING operand7 |
GIVING:
When the
When an error occurs and the When |
SUBCODE operand8 |
SUBCODE:
When the
If
Note: |
END-PARSE |
End of PARSE JSON Statement:
In structured mode, the Natural reserved keyword In reporting mode, the Natural statement |
LOOP |
The following code:
** Example 'PAJSNEX1': PARSE JSON (with PATH and CODEPAGE)
**
** Note: Definition of variable MYJSON needs TQMARK set to OFF.
************************************************************************
OPTIONS TQMARK=OFF /* Translate quotation mark
*
DEFINE DATA LOCAL
1 MYJSON (A) DYNAMIC
1 MYCODEPAGE (A) DYNAMIC
1 MYPATH (A) DYNAMIC
END-DEFINE
*
COMPRESS '{'
' "employee": {'
' "@personnel-id": "30016315",'
' "full-name": {'
' "first-name": "RICHARD",'
' "name": "FORDHAM"'
' }'
' }'
'}'
INTO MYJSON LEAVING NO
*
MYCODEPAGE := *CODEPAGE
*
PARSE JSON MYJSON ENCODED IN CODEPAGE MYCODEPAGE
INTO PATH MYPATH
PRINT MYPATH
END-PARSE
END
produces the following output:
< </employee </employee/< </employee/</@personnel-id </employee/</@personnel-id/$ </employee/</full-name </employee/</full-name/< </employee/</full-name/</first-name </employee/</full-name/</first-name/$ </employee/</full-name/</name </employee/</full-name/</name/$ </employee/</full-name/> </employee/> >
The following code:
** Example 'PAJSNEX2': PARSE JSON (with PATH and SEPARATOR)
**
** Note: Definition of variable MYJSON needs TQMARK set to OFF.
************************************************************************
OPTIONS TQMARK=OFF /* Translate quotation mark
*
DEFINE DATA LOCAL
1 MYJSON (A) DYNAMIC
1 MYCODEPAGE (A) DYNAMIC
1 MYPATH (A) DYNAMIC
1 MYSEPARATOR (A1)
END-DEFINE
*
COMPRESS '{'
' "employee": {'
' "@personnel-id": "30016315",'
' "full-name": {'
' "first-name": "RICHARD",'
' "name": "FORDHAM"'
' }'
' }'
'}'
INTO MYJSON LEAVING NO
*
MYCODEPAGE := *CODEPAGE
MYSEPARATOR := '*'
*
PARSE JSON MYJSON ENCODED IN CODEPAGE MYCODEPAGE
INTO PATH MYPATH WITH SEPARATOR MYSEPARATOR
PRINT MYPATH
END-PARSE
END
produces the following output:
< <*employee <*employee*< <*employee*<*@personnel-id <*employee*<*@personnel-id*$ <*employee*<*full-name <*employee*<*full-name*< <*employee*<*full-name*<*first-name <*employee*<*full-name*<*first-name*$ <*employee*<*full-name*<*name <*employee*<*full-name*<*name*$ <*employee*<*full-name*> <*employee*> >
The following code:
** Example 'PAJSNEX3': PARSE JSON (with PATH and NAME)
**
** Note: Definition of variable MYJSON needs TQMARK set to OFF.
************************************************************************
OPTIONS TQMARK=OFF /* Translate quotation mark
*
DEFINE DATA LOCAL
1 MYJSON (A) DYNAMIC
1 MYPATH (A) DYNAMIC
1 MYNAME (A) DYNAMIC
END-DEFINE
*
COMPRESS '{'
' "employee": {'
' "@personnel-id": "30016315",'
' "full-name": {'
' "first-name": "RICHARD",'
' "name": "FORDHAM"'
' }'
' }'
'}'
INTO MYJSON LEAVING NO
*
PARSE JSON MYJSON INTO PATH MYPATH NAME MYNAME
DISPLAY (AL=39) MYPATH MYNAME
END-PARSE
END
produces the following output:
MYPATH MYNAME ---------------------------------- ----------------------------------- < </employee employee </employee/< employee </employee/</@personnel-id @personnel-id </employee/</@personnel-id/$ </employee/</full-name full-name </employee/</full-name/< full-name </employee/</full-name/</first-name first-name </employee/</full-name/</first-name/$ </employee/</full-name/</name name </employee/</full-name/</name/$ </employee/</full-name/> </employee/> >
The following code:
** Example 'PAJSNEX4': PARSE JSON (with PATH and VALUE)
**
** Note: Definition of variable MYJSON needs TQMARK set to OFF.
************************************************************************
OPTIONS TQMARK=OFF /* Translate quotation mark
*
DEFINE DATA LOCAL
1 MYJSON (A) DYNAMIC
1 MYPATH (A) DYNAMIC
1 MYVALUE (A) DYNAMIC
END-DEFINE
*
COMPRESS '{'
' "employee": {'
' "@personnel-id": "30016315",'
' "full-name": {'
' "first-name": "RICHARD",'
' "name": "FORDHAM"'
' }'
' }'
'}'
INTO MYJSON LEAVING NO
*
PARSE JSON MYJSON INTO PATH MYPATH VALUE MYVALUE
DISPLAY (AL=39) MYPATH MYVALUE
END-PARSE
END
produces the following output:
MYPATH MYVALUE
--------------------------------------- ---------------------------------------
<
</employee
</employee/<
</employee/</@personnel-id
</employee/</@personnel-id/$ 30016315
</employee/</full-name
</employee/</full-name/<
</employee/</full-name/</first-name
</employee/</full-name/</first-name/$ RICHARD
</employee/</full-name/</name
</employee/</full-name/</name/$ FORDHAM
</employee/</full-name/>
</employee/>
>
The following program produces a runtime error:
** Example 'PAJSNEX5': PARSE JSON (with GIVING and SUBCODE)
**
** Note: Definition of variable MYJSON needs TQMARK set to OFF.
************************************************************************
OPTIONS TQMARK=OFF /* Translate quotation mark
*
DEFINE DATA LOCAL
1 MYJSON (A) DYNAMIC
1 MYPATH (A) DYNAMIC
1 MYNAME (A) DYNAMIC
1 MYVALUE (A) DYNAMIC
1 MYGIVING (I4)
1 MYSUBCODE (I4)
END-DEFINE
*
* Produce Natural runtime error with incorrect JSON document
*
COMPRESS '{'
' "employee": {'
' "@personnel-id": "30016315",'
' "full-name": {'
' "first-name": "RICHARD",'
' "FORDHAM"' /* here the key 'name' is missing
' }'
' }'
'}'
INTO MYJSON LEAVING NO
*
PARSE JSON MYJSON INTO PATH MYPATH NAME MYNAME VALUE MYVALUE
GIVING MYGIVING SUBCODE MYSUBCODE
WRITE (AL=39) MYPATH
END-PARSE
*
IF MYGIVING NE 0
WRITE / 'Error Number:' MYGIVING 'Subcode:' MYSUBCODE
END-IF
END
output of the given program:
<
</employee
</employee/<
</employee/</@personnel-id
</employee/</@personnel-id/$
</employee/</full-name
</employee/</full-name/<
</employee/</full-name/</first-name
</employee/</full-name/</first-name/$
</employee/</full-name/</FORDHAM
Error Number: 8331 Subcode: 5