ENTMF 

The JSON PARSE Statement

The JSON PARSE statement converts JSON text to COBOL data formats. It matches the JSON name/value pairs to COBOL identifiers, and then populates them.

General Format

JSON PARSE Statement

phrase-1

Phrase 1 JSON PARSE

using-phrase-1

Uisng phrase 1 JSON PARSE

General Rules

  1. Identifier-1 is the data item that contains the JSON text.
  2. The JSON text identified by identifier-1 is assumed to be encoded in UTF-8.
  3. If identifier-1 contains invalid JSON syntax, the statement terminates with an exception condition, and identifier-2 may be partially modified.
  4. Identifier-2 is the group or elementary item populated with the JSON text.
  5. When the WITH DETAIL phrase is specified, JSON PARSE generates run-time error messages when it encounters both non-exception and exception conditions.
  6. The NAME OF phrase enables you to use a different data name than the one required by the matching algorithm when matching the name of a JSON name/value pair to a COBOL data item. See Appendix C - Matching Algorithm Examples for more information.
  7. The NAME OF phrase must not result in an ambiguous name specification, and is in effect during the execution of the JSON PARSE statement.
  8. The SUPPRESS phrase enables you to exclude items that are subordinate to identifier-2 from being parsed.
  9. The CONVERTING phrase enables you to specify items to be parsed as JSON BOOLEAN name/value pairs; use the ALSO keyword to specify multiple items.
  10. When an exception occurs, if the ON EXCEPTION phrase is specified, control is passed to imperative-statement-1, and the NOT ON EXCEPTION phrase, if specified, is ignored. If the ON EXCEPTION phrase is not specified, control is transferred to the end of the statement. Such conditions can occur when the JSON text is ill-formed or there are problems populating identifier-2 with the JSON text.
  11. When an exception occurs, the parsing operation is halted, but identifier-2 may be partially modified.
  12. On exception, special register JSON-CODE contains the exception code; see JSON-CODE Exception Codes.
  13. The special register JSON-STATUS may also contain a non-zero value, indicating one or more non-exception conditions that occurred before the exception occurred. See JSON-STATUS Non-Exception Codes.
  14. If an exception does not occur, and the NOT ON EXCEPTION phrase is specified, control is passed to imperative-statement-2; otherwise control is transferred to the end of the statement, and special register JSON-CODE contains zero after statement execution.
  15. Non-exception conditions during statement execution can result in special register JSON-STATUS being set to a nonzero value, and identifier-2 may be partially modified.
  16. During parsing, whitespace characters (SP, HT, LF, and CR) are ignored, except within strings, and are illegal within numbers.
  17. OMITTED can be specified to parse an anonymous JSON object, whose top parent name is not specified.
  18. Use the using-phrase-1 to specify the values that will be moved into identifier-5 when a JSON BOOLEAN true or false value is encountered during parsing.

Syntax Rules

  1. Identifier-1 must reference one of the following: an elementary data item of category alphanumeric; an alphanumeric group item.
  2. When identifier-1 references an alphanumeric group item, it is treated as though it is an elementary data item of category alphanumeric.
  3. Identifier-1 must not be defined with the JUSTIFIED clause.
  4. Identifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.
  5. Identifier-1 cannot be a function identifier.
  6. Identifier-1 can be subscripted or reference modified.
  7. Identifier-1 must not overlap identifier-2.
  8. Identifier-2 must be an alphanumeric group item, or elementary data item of category alphanumeric
  9. Identifier-2, the group or elementary item destined to hold the JSON text, cannot be reference modified, but it can be subscripted.
  10. Identifier-2 cannot be a function identifier.
  11. Identifier-2 must not overlap identifier-1.
  12. Identifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.
  13. Identifier-2 must not specify the UNBOUNDED or RENAMES clause. Subordinate data must also not specify the UNBOUNDED clause.
  14. The following data items specified by identifier-2 are ignored by the JSON PARSE statement:
    • Subordinate unnamed elementary data items.
    • Elementary FILLER data items.
    • Slack bytes inserted for SYNCHRONIZED data items.
    • Subordinate items defined with the REDEFINES clause, or items subordinate to such a redefining item.
    • Subordinate items defined with the RENAMES clause.
    • Any group item whose subordinate data items are all ignored.
  15. Data items specified by identifier-2 that are not ignored according to the previous rules must adhere to the following:
    • There must be at least one elementary data item.
    • Elementary data items must have a USAGE other than DISPLAY-1, FUNCTION-POINTER, INDEX, OBJECT REFERENCE, POINTER, or PROCEDURE-POINTER.
    • Each non-FILLER data name must be unique within identifier-2.
    • If the data declaration of identifier-2, or any of its subordinate items, contains the OCCURS DEPENDING ON clause, then the target of that clause must not be subordinate to identifier-2. Thus, any objects of OCCURS DEPENDING ON clauses are not updated by the JSON PARSE statement.
  16. Identifier-3 must reference identifier-2 or one of its subordinates.
  17. Identifier-3 cannot be a function identifier, reference modified or subscripted.
  18. Identifier-3 cannot specify any data item that is ignored according to the above restrictions.
  19. Identifier-3 may be specified more than once, but only the last specification is used.
  20. Literal-1 must be alphanumeric or a national literal containing the JSON name to be associated with identifier-3.
  21. Identifier-4 must reference an item that is subordinate to identifier-2 and that is not otherwise ignored according to the above restrictions.
  22. Identifier-4 cannot be a function identifier, subscripted or reference modified.
  23. Identifier-4 can reference an entire table.
  24. If identifier-4 specifies a group item, that group item and all of its subordinates are excluded.
  25. Duplicate specifications of identifier-4 are permitted.
  26. If a data item is specified in both the NAME phrase and the SUPPRESS phrase, it is excluded.
  27. Identifier-5 must be a single-byte alphanumeric elementary data item whose data definition entry contains PICTURE X.
  28. Condition-name-1 must be a level-88 item which is directly subordinate to identifier-5. It must be specified with both the VALUE clause and the WHEN SET TO FALSE phrase. The first VALUE clause literal (for there could be multiple specified) is used to populate identifier-5 when parsing a JSON BOOLEAN true value. The FALSE value populates identifier-5 when parsing a JSON BOOLEAN false value.
  29. Condition-name-2 and Condition-name-3 must be level-88 items directly subordinate to identifier-5. Their VALUE clauses are used to populate identifier-5 when a JSON BOOLEAN true or false value is parsed respectively. The first VALUE clause literal is used in both cases.
  30. Literal-2 and literal-3 must be single-byte alphanumeric literals. Literal-2 and literal-3 are used to populate identifier-5 when a JSON BOOLEAN true or false value is parsed respectively
Parent topic: Statements
Related concepts
Tutorial: Parsing a JSON text string
Related reference
JSON-STATUS Non-Exception Codes
JSON-CODE Exception Codes