The JSON GENERATE Statement

The JSON GENERATE statement converts data to JSON format.

General Format

JSON GENERATE Statement

Syntax Rules

Identifier-1 must be either: an elementary data item of category alphanumeric, or an alphanumeric group item
When identifier-1 is 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.
Identifier-1, identifier-2, identifier-4, or identifier-5 cannot be a function identifier.
Identifier-1 can be subscripted or reference modified.
Identifier-1 must not overlap identifier-2 or identifier-3.
The generated JSON text is encoded in UTF-8 (codepage 1208).
Identifier-1 must be large enough to contain the generated JSON text. Typically, it should be from 2 to 3 times the size of identifier-2, depending on the lengths of the data-names within identifier-2. If identifier-1 is not large enough, an exception condition exists at the end of the JSON GENERATE statement. If the COUNT phrase is specified, identifier-3 contains the number of character encoding units that were actually generated.
If the SUPPRESS phrase is in effect, identifier-1 must still be large enough to contain the generated JSON text before suppression.
Identifier-2 cannot be reference modified, but it can be subscripted.
Identifier-2 must not overlap identifier-1 or identifier-3, or must not specify the RENAMES clause.
If identifier-2 is set to any of the following, they are ignored by the JSON GENERATE 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; and any group data item whose subordinate data items are all 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 POINTER, FUNCTION-POINTER, PROCEDURE-POINTER, or OBJECT REFERENCE; there must be at least one such elementary data item; and each non-FILLER data-name must be unique within any immediately superordinate group data item.
Identifier-3 must be an integer data item defined without the symbol P in its picture string.
Identifier-3 must not overlap identifier-1, identifier-2, identifier-4, or identifier-5.
Identifier-4 must reference identifier-2 or one of its subordinate data items.
Identifier-4 or identifier-5 cannot be reference modified or subscripted.
Identifier-4 cannot specify any data item which is ignored by the JSON GENERATE statement.
Literal-1 must be an alphanumeric containing the name to be generated in the JSON text corresponding to identifier-4. Alternatively, you can specify OMITTED to generate an anonymous JSON object, whose top-level parent name is not generated. When you specify OMITTED, identifier-4 must reference identifier-2.
Identifier-5 explicitly identifies items to be potentially suppressed. It must reference a data item that is subordinate to identifier-2, and that is not otherwise ignored by the operation of the JSON GENERATE statement. identifier-5 cannot be a function identifier, cannot be modified by reference, and cannot be subscripted.
You may duplicate specifications of identifier-5.
Identifier-5 must reference an elementary data item if the WHEN phrase is specified. If WHEN is omitted, identifier-5 may be a group item, and in the case that it is a group item, that group data item and all data items that are subordinate to the group item are excluded.
When used with the WHEN phrase, identifier-5:
- May specify one or more of the following values per data item, separated by the OR keyword:
  - ZERO
  - ZEROES
  - ZEROS
  - SPACE
  - SPACES
  - LOW-VALUE
  - LOW-VALUES
  - HIGH-VALUE
  - HIGH-VALUES
Note: A data item affected by the WHEN phrase must be an elemental data item. If the data item is numeric and the value specified with the WHEN phrase is ZERO, ZEROES, or ZEROS, the comparison is numeric. Otherwise, the comparison is alphanumeric.

General Rules

Identifier-1 is the receiving area for the generated JSON text.
Identifier-2 is the group or elementary data item to be converted to JSON format.
If the COUNT phrase is specified, identifier-3 contains (after successful execution of the JSON GENERATE statement) the count of generated JSON character encoding units.
The NAME phrase enables you to override the default JSON names derived from identifier-2 or its subordinate data items.
If the NAME phrase specifies identifier-4 more than once, the last specification is used.
The SUPPRESS phrase enables you to selectively generate output for the JSON GENERATE statement by allowing you to identify and unconditionally exclude items that are subordinate to identifier-2.
If identifier-5 specifies a group data item, that group data item and all subordinate data items are excluded.
Duplicate specifications of identifier-5 are permitted.
When the SUPPRESS phrase is specified, a group item subordinate to identifier-2 is excluded from the generated JSON text if all eligible items subordinate to the group item are excluded. The outermost object that corresponds to identifier-2 itself is always generated, even if all subordinate items to identifier-2 are excluded. In this case, the value generated for identifier-2 is an empty object, as follows :
```
{"identifier-2":{}}
```
Unless explicitly suppressed, an ODO table with no elements is always retained in the JSON text as follows:
```
{"table-name":[]}
```
If the ON EXCEPTION phrase is specified, control transfers to imperative-statement-1 when an error occurs during generation of the JSON document.
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 GENERATE statement in the event of an error.
In the event of an error, the JSON-CODE special register contains the exception code; see JSON-CODE Exception Codes for more information.
If an exception condition does not occur during generation of the JSON document, control is passed to imperative-statement-2, if specified; otherwise, control is passed to the end of the JSON GENERATE statement. The ON EXCEPTION phrase, if specified, is ignored, and special register JSON-CODE contains zero after execution of the JSON GENERATE statement.
The END-JSON phrase is the scope terminator that delimits the scope of the statement.
Use of END-JSON allows a conditional JSON GENERATE statement (that is, a JSON GENERATE 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 statement can be terminated by either an END-JSON phrase or a separator period.
END-JSON can also be used with a JSON GENERATE statement that does not specify either the ON EXCEPTION or the NOT ON EXCEPTION phrase.
JSON GENERATE statements that appear in imperative-statement-1 or imperative-statement-2 of another JSON GENERATE statement are nested JSON GENERATE statements. Nested JSON GENERATE statements are considered to be matched JSON GENERATE and END-JSON combinations, proceeding from left to right. Thus, any END-JSON phrase that is encountered is matched with the nearest preceding JSON GENERATE statement that has not been implicitly or explicitly terminated.