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

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. 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.
  10. When an exception occurs, the parsing operation is halted, but identifier-2 may be partially modified.
  11. On exception, special register JSON-CODE contains the exception code; see JSON-CODE Exception Codes.
  12. 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.
  13. 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.
  14. 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.
  15. During parsing, whitespace characters (SP, HT, LF, and CR) are ignored, except within strings, and are illegal within numbers.

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 cannot be a function identifier.
  5. Identifier-1 can be subscripted or reference modified.
  6. Identifier-1 must not overlap identifier-2.
  7. Identifier-2 must be an alphanumeric group item, or elementary data item of category alphanumeric
  8. Identifier-2, the group or elementary item destined to hold the JSON text, cannot be reference modified, but it can be subscripted.
  9. Identifier-2 cannot be a function identifier.
  10. Identifier-2 must not overlap identifier-1.
  11. Identifier-2 must not specify the UNBOUNDED or RENAMES clause. Subordinate data must also not specify the UNBOUNDED clause.
  12. 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.
  13. 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.
  14. Identifier-3 must reference identifier-2 or one of its subordinates.
  15. Identifier-3 cannot be a function identifier, reference modified or subscripted.
  16. Identifier-3 cannot specify any data item that is ignored according to the above restrictions.
  17. Identifier-3 may be specified more than once, but only the last specification is used.
  18. Literal-1 must be alphanumeric or a national literal containing the JSON name to be associated with identifier-3.
  19. Identifier-4 must reference an item that is subordinate to identifier-2 and that is not otherwise ignored according to the above restrictions.
  20. Identifier-4 cannot be a function identifier, subscripted or reference modified.
  21. Identifier-4 can reference an entire table.
  22. If identifier-4 specifies a group item, that group item and all of its subordinates are excluded.
  23. Duplicate specifications of identifier-4 are permitted.
  24. If a data item is specified in both the NAME phrase and the SUPPRESS phrase, it is excluded.
Parent topic: Statements