Operation of JSON PARSE

The JSON text must be valid. Otherwise the statement terminates with an exception condition, and identifier-2 might be partially modified.

Parsing is guided by a name-matching algorithm in which the containment structure of the names must match exactly, except that omissions of complete elementary or "group" levels are tolerated in the JSON text. For both the JSON name and the COBOL data name, each lowercase single-byte alphabetic letter, a through z, is considered to be equivalent to its corresponding single-byte uppercase alphabetic letter, A through Z. In other words, the name-matching between JSON names and COBOL data names is case insensitive. In the case of an applicable NAME phrase specification, the NAME phrase literal, after being converted by the compiler from the codepage in effect by the CODEPAGE compiler option to Unicode UTF-8, must match the JSON name exactly in a case sensitive match.

For each matching JSON name and data item name, the matching JSON value is assigned to the corresponding data item and occurrence in accordance with the table of Valid and invalid elementary moves, and with the same semantics as the equivalent COBOL MOVE statement.

Whitespace characters (SP, HT, LF, and CR) are ignored, except within strings, and are illegal within numbers.

If, for each elementary data item subordinate to identifier-2, there is exactly one matching appropriately qualified JSON name/value pair, regardless of the order in the JSON text, then the JSON PARSE statement terminates without an exception, and with special registers JSON-STATUS and JSON-CODE containing zero.

A number of other conditions encountered during execution of the JSON PARSE statement might result in a nonzero JSON-STATUS value, or an exception and a nonzero JSON-CODE value.

For example, if any combination of JSON value and COBOL data type is invalid, the statement terminates with an exception condition. If any matching JSON value results in one or more substitution characters when translated from Unicode to the CCSID specified by the CODEPAGE compiler option, the value is accepted but results in a nonzero JSON-STATUS value and possibly one or more runtime messages, under control of the WITH DETAIL phrase.

Superfluous JSON name/value pairs that do not match any data item names in identifier-2 are tolerated, but result in setting special register JSON-STATUS to a condition code, and possibly in one or more runtime messages, under control of the WITH DETAIL phrase.

If there are no matching items, the statement terminates with an exception condition, and identifier-2 is unmodified.

The special value null is interpreted as an instruction to skip assignment of the corresponding data item or occurrence.

This could be useful for tables. For example parsing the JSON text fragment:

{"myTable":[31, null, 37, null, 41]}

would result in setting only the first, third, and fifth occurrences of data item “myTable”.

Each JSON array should have the same cardinality as the associated table data item. If the JSON array has fewer elements than the table item, the additional table elements are not modified. If the JSON array has more values than the matching table item, the additional values are ignored. Both kinds of mismatch result in a nonzero JSON-STATUS setting.

For a complete description of JSON PARSE conditions, see JSON PARSE conditions and associated codes and runtime messages in the Enterprise COBOL Programming Guide.