The JSON GENERATE Statement

The JSON GENERATE statement converts data to JSON format.

General Format

JSON GENERATE Statement

when-phrase

generic-suppression-phrase

phrase-1

Syntax Rules

Identifier-1 must be either: an elementary data item of category alphanumeric; an alphanumeric group item; an elementary data item of category national; or a national group item
When identifier-1 is a national group item, identifier-1 is processed as an elementary data item of category national.
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.
Identifier-1 must not be a dynamic-length group item or a dynamic-length elementary item.
The generated JSON text is encoded in UTF-16 big-Endian (codepage 1200) if identifier-1 is of category national; otherwise, it 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 be a dynamic-length group item or a dynamic-length elementary item.
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, subscripted, or a function identifier.
Identifier-4 cannot specify any data item which is ignored by the JSON GENERATE statement.
Literal-1 must be an alphanumeric or national literal 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 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-6 must be a single-byte alphanumeric elementary data item whose data definition entry contains PICTURE X.
Condition-name-1 must be a level-88 item directly subordinate to identifier-6 and can be specified with multiple values or value ranges.
Literal-2 must be a single-byte alphanumeric literal.

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. If identifier-1 (the receiver) is of category national, the count is in double-bytes. Otherwise, the count is in bytes.
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 conditionally exclude items that are subordinate to identifier-2.
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”:[]}
```
Identifier-5 explicitly identifies items for potential suppression. It must reference a data item subordinate to identifier-2 that is not otherwise ignored by the JSON GENERATE operation.
If the WHEN phrase is specified, identifier-5 must reference an elementary data item, but if the WHEN phrase is omitted, identifier-5 can be a group item. When a group data item is identified, that group data item and all subordinate data items are excluded.
Duplicate specifications of identifier-5 are permitted.
The rules for potential suppression when using identifier-5 are as follows:
- When specifying WHEN ZERO/ZEROES/ZEROS, identifier-5 cannot be of USAGE DISPLAY-1.
- When specifying WHEN SPACE/SPACES, identifier-5 must be of USAGE DISPLAY, DISPLAY-1, or NATIONAL. If it is a zoned or national decimal item, it must be an integer.
- When specifying WHEN LOW-VALUE/LOW-VALUES/HIGH-VALUE/HIGH-VALUES, identifier-5 must be of USAGE DISPLAY or NATIONAL. If it is a zoned or national decimal item, it must be an integer.
The generic-suppression-phrase identifies elementary items subordinate to identifier-2, that are not otherwise ignored by JSON GENERATE operations, for potential suppression. These are identified according to the NUMERIC and NONUMERIC keywords; omit both keywords to identify both types.
The effect of specifying multiple generic-suppression-phrases is cumulative.
The rules for potential suppression when using the generic-suppression-phrase are as follows:
- If ZERO, ZEROES, or ZEROS is specified in the WHEN phrase, all data items except those that are defined with USAGE DISPLAY-1 are selected.
- If SPACE or SPACES is specified in the WHEN phrase, data items of USAGE DISPLAY, DISPLAY-1, or NATIONAL are selected. For zoned or national decimal items, only integers are selected.
- If LOW-VALUE, LOW-VALUES, HIGH-VALUE, or HIGH-VALUES is specified in the WHEN phrase, data items of USAGE DISPLAY or NATIONAL are selected. For zoned or national decimal items, only integers are selected.
When determining potential suppression items, if the item is of class numeric and WHEN ZERO/ZEROES/ZEROS has been specified, a numeric comparison is performed. For all other items, the comparison is alphanumeric, DBCS, or national, depending on whether the item is of usage DISPLAY, DISPLAY-1, or NATIONAL, respectively.
The CONVERTING phrase enables you to specify items that will be generated as JSON BOOLEAN name/value pairs. The condition-name-1 and literal-2 specifications represent the generated JSON BOOLEAN true value, whereas all other values are generated as JSON BOOLEAN false. The ALSO keyword can be used to specify multiple JSON BOOLEAN name/value pairs.
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.