JSON PARSE statement

You can watch this video to get an overview of the JSON support in Enterprise COBOL V6.

Format

phrase-1 Format

using-phrase-1 Format

identifier-1

The data item that contains the JSON text. identifier-1 must reference one of the following items:

• An elementary data item of category alphanumeric
• An alphanumeric group item

When identifier-1 references an alphanumeric group item, identifier-1 is treated as though it were an elementary data item of category alphanumeric.

identifier-1 must not be defined with the JUSTIFIED clause, and cannot be a function identifier. identifier-1 can be subscripted or reference modified.

identifier-1 must not overlap identifier-2.

identifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.

The JSON text is assumed to be encoded in UTF-8 (CCSID 1208).

All the escaped character sequences defined in the JSON specification are accepted. Also accepted is the sequence “\x”, which is generated by JSON GENERATE, and which represents the EBCDIC NL (newline) control character X'15', equivalent to the Unicode NEXT LINE control character, NX'0085'.

Conversion from Unicode of the JSON names and values is done according to the compiler CODEPAGE option in effect for the compilation.

identifier-2

The group or elementary data item to be populated from the JSON text.

identifier-2 cannot be a function identifier or be reference modified, but it can be subscripted.

identifier-2 must not overlap identifier-1.

identifier-2 and its subordinate data items must not contain the UNBOUNDED clause.

identifier-2 must not be a dynamic-length group item or a dynamic-length elementary item.

The data description entry for identifier-2 must not contain a RENAMES clause.

The following data items that are specified by identifier-2 are ignored by the JSON PARSE statement:

• Any subordinate unnamed elementary data items or elementary FILLER data items
• Any slack bytes inserted for SYNCHRONIZED items
• Any data item subordinate to identifier-2 that is defined with the REDEFINES clause or that is subordinate to such a redefining item
• Any data item subordinate to identifier-2 that is defined with the RENAMES clause
• Any group data item all of whose subordinate data items are ignored

All data items specified by identifier-2 that are not ignored according to the previous rules must satisfy the following conditions:

• Each elementary data item must have a USAGE other than DISPLAY-1, FUNCTION-POINTER, INDEX, OBJECT REFERENCE, POINTER, or PROCEDURE-POINTER.
• There must be at least one such elementary data item.
• Each non-FILLER data-name must have a unique identifier within identifier-2.
• If (the data declaration of) identifier-2 or any subordinate data item contains the OCCURS DEPENDING ON clause, then the object(s) of the OCCURS DEPENDING ON clause(s) must not be subordinate to identifier-2. Thus, any objects of OCCURS DEPENDING ON clauses will not be updated by the JSON PARSE statement.

WITH DETAIL phrase

The WITH DETAIL phrase causes the JSON PARSE statement to emit runtime messages for any nonexception and exception conditions encountered during parsing.

NAME phrase

For the purpose of matching the name of a JSON name/value pair, the NAME phrase allows you to effectively change the name of a data item to the specified literal during the execution of the JSON PARSE statement.

OMITTED can be specified to parse an anonymous JSON object, whose top parent name is not specified.

identifier-3 must reference identifier-2 or one of its subordinate data items. It cannot be a function identifier and cannot be reference modified or subscripted. It must not specify any data item which is ignored by the JSON PARSE statement. For more information about identifier-2, see the description of identifier-2. If identifier-3 is specified more than once in the NAME phrase, the last specification is used. If OMITTED is specified, identifier-3 must refer to identifier-2.

literal-1 must be an alphanumeric or national literal containing the JSON name to be associated with identifier-3. The literal is case-sensitive and must match the JSON name exactly.

The NAME phrase in aggregate must not result in an ambiguous name specification. For example, given the following data declarations and JSON text:

01 G.
   05 H.
      10 A pic x(10).
      10 3_ pic 9.
      10 C-C pic x(10).

'{"g": {"H": {"A": "Eh?", "3_": 5, "C-C": "See"}}}'.

Then, if it were allowed, specifying the NAME phrase as:

NAME of A is 'C-C'

would result in no data item receiving the value "Eh?", and an ambiguity about which data item should receive the value "See", effectively defining the declaration of group G as:

01 G.
   05 H.
      10 C-C pic x(10).
      10 3_ pic 9.
      10 C-C pic x(10).

which would be illegal if referenced as identifier-2 in a JSON PARSE statement. Specifying the NAME phrase as:

NAME of A is 'C-C' C-C is 'A'

is not ambiguous, and would simply swap the assignments to data items A and C-C.

Given the following data declaration and JSON text:

01. top
02. A pic x(20).
03. B pic x(20).

'{"A":"value1","B":"value2"}'

This JSON object can be parsed using OMITTED:

NAME top IS OMITTED

If OMITTED is not specified, the JSON object would need to contain a parent name called "top":

'{"top":{"A":"value1","B":"value2"}}'

SUPPRESS phrase

Allows you to identify and unconditionally exclude items that are subordinate to identifier-2 from assignment by the JSON PARSE statement.

identifier-4 must reference a data item that is subordinate to identifier-2 and that is not otherwise ignored by the operation of the JSON PARSE statement. identifier-4 cannot be a function identifier and cannot be reference modified or subscripted. identifier-4 can reference an entire table.

If identifier-4 specifies a group data item, that group data item and all data items that are subordinate to the group item are excluded.

Duplicate specifications of identifier-4 are permitted.

A data item that is specified in the SUPPRESS phrase, is suppressed even if the same data item is also specified in the NAME phrase.

CONVERTING phrase

Allows you to specify items that will be parsed as JSON BOOLEAN name/value pairs.

identifier-5 must be a single-byte alphanumeric elementary data item whose data definition entry contains PICTURE X.

The USING phrase provides various methods of specifying the values that shall be effectively moved into identifier-5 when a JSON BOOLEAN true or false value is encountered during parsing.

condition-name-1 must be a level-88 item directly subordinate to identifier-5 and must be specified with both the VALUE clause and the WHEN SET TO FALSE phrase. The first VALUE clause literal (of possibly many values and ranges) will be used to populate identifier-5 when parsing a JSON BOOLEAN true value. The FALSE value will be used to populate identifier-5 when parsing a JSON BOOLEAN false value.

condition-name-2 and condition-name-3 must be level-88 items directly subordinate to identifier-5 whose VALUE clauses are used to populate identifier-5 when a JSON BOOLEAN true or false value is parsed respectively. The first VALUE clause literal will be used in both cases.

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.

The CONVERTING phrase can be specified with multiple items to be parsed as JSON BOOLEAN name/value pairs by using the ALSO keyword.

Example: CONVERTING phrase with all three formats of the USING phrase

Consider the following COBOL structure and statements:

01 docx pic x(1000).
01 myrecord.
  02 data-a pic x.
    88 data-a-flag value ‘T’ false ‘F’.
  02 data-b pic x.
    88 data-b-true value ‘1’.
    88 data-b-false value ‘0’.
  02 data-c pic x.

JSON PARSE docx INTO myrecord
  CONVERTING data-a FROM BOOLEAN USING data-a-flag
        ALSO data-b FROM BOOLEAN USING data-b-true AND data-b-false
        ALSO data-c FROM BOOLEAN USING ‘a’ AND ‘z’
DISPLAY data-a
DISPLAY data-b
DISPLAY data-c

Assume docx contains the following UTF-8 encoded JSON text:

{ “myrecord” :
  { “data-a” : true,
    “data-b” : false,
    “data-c” : true
  }
}

The output of the program would be:

T
0
a

ON EXCEPTION phrase

An exception condition exists when an error occurs during parsing of the JSON text, for example an ill-formed JSON value, or during assignment of a value to a COBOL data item. In such cases, JSON parsing stops and the receiver, identifier-2, might be partially modified.

Special register JSON-CODE contains an exception code, as detailed in JSON PARSE conditions and associated codes and runtime messages in the Enterprise COBOL Programming Guide. Special register JSON-STATUS might also contain a nonzero status value, representing one or more non-exception conditions that occurred prior to the exception condition. For more details, see Operation of JSON PARSE.

If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. If the ON EXCEPTION phrase is not specified, the NOT ON EXCEPTION phrase, if any, is ignored, and control is transferred to the end of the JSON PARSE statement.

NOT ON EXCEPTION phrase

If an exception condition does not occur during parsing of the JSON text, control is passed to imperative-statement-2, if specified, otherwise to the end of the JSON PARSE statement. The ON EXCEPTION phrase, if specified, is ignored. Special register JSON-CODE contains zero after execution of the JSON PARSE statement.

Nonexception conditions that can occur during execution of the JSON PARSE statement might result in special register JSON-STATUS being set to a nonzero status value, and the receiver identifier-2 being partially modified.

For more details, see “Operation of JSON PARSE” and JSON PARSE conditions and associated codes and runtime messages in the Enterprise COBOL Programming Guide.

END-JSON phrase

This explicit scope terminator delimits the scope of JSON GENERATE or JSON PARSE statements. END-JSON permits a conditional JSON GENERATE or JSON PARSE statement (that is, a JSON GENERATE or JSON PARSE statement that specifies the ON EXCEPTION or NOT ON EXCEPTION phrase) to be nested in another conditional statement.

The scope of a conditional JSON GENERATE or JSON PARSE statement can be terminated by:

• An END-JSON phrase at the same level of nesting
• A separator period

END-JSON can also be used with a JSON GENERATE or JSON PARSE statement that does not specify either the ON EXCEPTION or the NOT ON EXCEPTION phrase.

For more information about explicit scope terminators, see Delimited scope statements.