PARSE JSON

#### Search Results

Search

# PARSE JSON

`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` [(r)] | (structured mode only)
`LOOP` [(r)] | (reporting mode only)

This document covers the following topics:

- PARSE JSON Usage

- PARSE JSON Syntax Description

- PARSE JSON Examples

- PARSE JSON: Reason Codes for Error Message NAT8331

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.

## PARSE JSON Usage

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.

### Mark-Up

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 You can customize the separator marker using `operand2` |
`$` | 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.

### Related System Variables

The following Natural system variables are automatically created for each `PARSE JSON` statement that is executed:

- `*PARSE-TYPE`

- `*PARSE-LEVEL`

- `*PARSE-INDEX`

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.

## PARSE JSON Syntax Description

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: `Operand2` denotes the code page of the JSON document represented by `operand1`
`PATH operand3` | Path: `Operand3` represents the `PATH` of a data in the JSON document. The `PATH` contains the `NAME` of the identified JSON part, the `NAME`s of all parents, as well as the type of the JSON part. Every name in the `PATH` is separated by `operand4` called Separator. Note The information given with `PATH` can be used to easily fill a tree view. See also Example 1 - Using the PATH Option.
`SEPARATOR operand4` | Separator: `Operand4` represents the Separator sign used to separate `NAME` and `Mark-Up` in the `PATH` (`operand3`). The default Separator sign used in the `PATH` (`operand3`) is a slash (`/`). See also Example 2 - Using the PATH with SEPARATOR Option.
`NAME operand5` | Data Element Name: `Operand5` represents the `NAME` of a data element in the JSON document. If `NAME` has no value, then the dynamic variable associated with it is set to `*LENGTH()=0`, which is a static variable filled with a blank. See also Example 3 - Using the NAME Option.
`VALUE operand6` | Data Element Content: `Operand6` represents the content (`VALUE`) of a data element in the JSON document. If there is no value, a given dynamic variable associated with it is set to `*LENGTH()=0`, which is a static variable filled with a blank. See also Example 4 - Using the VALUE Option.
`GIVING operand7` | GIVING: When the `PARSE` process encounters an error at runtime, `operand7` holds the 4-digit Natural error number. `Operand7` is updated at the end of each iteration in a parse process. `GIVING` applies only to error code NAT8331. If the `GIVING` parameter is specified, `operand7` returns `0` in the absence of an error. However, if a `PARSE` error occurs, `operand7` returns an appropriate Natural error number. When an error occurs and the `GIVING` parameter is specified, the `PARSE` loop is terminated and control is passed back to the statement following `END-PARSE`. When `GIVING` is not set and an error occurs, a Natural error message is returned and program execution is suspended, unless the `ON ERROR` statement block is used. See also Example 5 - Using the GIVING and SUBCODE Clauses.
`SUBCODE operand8` | SUBCODE: When the `PARSE` process encounters an error at runtime, `operand8` holds the 3-digit Reason Code associated with the error number in `operand7`. `Operand8` is updated at the end of each iteration in a parse process. If `SUBCODE` parameter is specified, `operand8` returns `0` in the absence of an error. However, if a `PARSE` error occurs, `operand8` returns an appropriate reason code. `SUBCODE` applies only to error code NAT8331. When the `SUBCODE` operand is provided along with `GIVING` and an error occurs, the `PARSE` loop is terminated and control is returned to the statement following `END-PARSE`. Note You can find the list of all reason codes for Natural error NAT8331 under JSON PARSE: Reason Codes for Error Message NAT8331. See also Example 5 - Using the GIVING and SUBCODE Clauses.
`END-PARSE (r)` | End of PARSE JSON Statement: In structured mode, the Natural reserved keyword `END-PARSE` must be used to end the `PARSE JSON` statement. You can specify labels or line numbers with `END-PARSE` in structured mode. In reporting mode, the Natural statement `LOOP` is used to end the `PARSE JSON` statement. You can specify labels or line numbers with `LOOP` in reporting mode.
`LOOP (r)`

## PARSE JSON Examples

- Example 1 - Using the PATH Option

- Example 2 - Using the PATH with SEPARATOR Option

- Example 3 - Using the NAME Option

- Example 4 - Using the VALUE Option

- Example 5 - Using the GIVING and SUBCODE Clauses

### Example 1 - Using the PATH Option

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/>
    >

### Example 2 - Using the PATH with SEPARATOR Option

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*>
    >

### Example 3 - Using the NAME Option

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/>
    >

### Example 4 - Using the VALUE Option

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/>
    >

### Example 5 - Using the GIVING and SUBCODE Clauses

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

## PARSE JSON: Reason Codes for Error Message NAT8331

If the JSON parsing process terminates with error message NAT8331, the JSON input document is syntactically invalid. The reason codes returned, along with NAT8331, represent the following meanings:

##### Reason Codes for Error Message NAT8331

Reason Code | Explanation
--- | ---
001 | An internal error has occurred, and the `PARSE` process cannot proceed.
002 | There is a generic syntax error.
003 | `VALUE` is missing (or) JSON document is `BLANK`.
004 | `KEY` is missing.
005 | `COLON` is missing.
006 | Either a `COMMA` (or) close of array/object is missing.
007 | String not properly closed.
008 | Invalid/unknown escape sequence (in a string).
009 | Invalid UTF-8 (in a string).
010 | The JSON document is empty.
211 | The document root must not follow by other values.
212 | Invalid escape character in string.
213 | Invalid encoding in string.
214 | Number too big to be stored in double.
215 | Missing fraction part in number.
216 | Missing exponent in number.

### On this page

- PARSE JSON Usage
- PARSE JSON Syntax Description
- PARSE JSON Examples
- PARSE JSON: Reason Codes for Error Message NAT8331