JSON GENERATE statement

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

Format

when-phrase Format

generic-suppression-phrase Format

converting-phrase Format 1

converting-phrase Format 2

indicating-phrase-1 format

identifier-1

The receiving area for the generated JSON text. identifier-1 must reference one of the following items:

• An elementary data item of category alphanumeric
• An alphanumeric group item
• An elementary data item of category national
• A national group item
• An elementary data item of category UTF-8
• A UTF-8 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. When identifier-1 references a national group item, identifier-1 is processed as an elementary data item of category national. When identifier-1 references a UTF-8 group item, identifier-1 is processed as an elementary data item of category UTF-8.

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 or identifier-3.

identifier-1 can be a dynamic-length elementary item of category alphanumeric or UTF-8. identifier-1 cannot be a dynamic-length group item of any category, nor an elementary item of category national.

The generated JSON text is encoded in UTF-8 (CCSID 1208), except in the following scenarios:

• identifier-1 is of category national, in which case it is encoded in UTF-16 Big-Endian (CCSID1200)
• identifier-1 is of category alphanumeric and the ENCODING phrase is specified with an EBCDIC CCSID

Conversion of the data values and NAME phrase literals is done according to the CODEPAGE compiler option in effect for the compilation. Conversion of original data names is always done using CCSID 1140. For details, see CODEPAGE in the Enterprise COBOL Programming Guide.

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.

identifier-2

The group or elementary data item to be converted to JSON format. identifier-2 must reference one of the following items:

• An elementary data item of category alphanumeric
• An alphanumeric group item
• An elementary data item of category national
• A national group item
• An elementary data item of category UTF-8
• A UTF-8 group item

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

identifier-2 must not overlap identifier-1 or identifier-3.

identifier-2 can be a dynamic-length group item or a dynamic-length elementary item of category alphanumeric or UTF-8. identifier-2 cannot be a dynamic-length group or elementary item of category national.

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 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
• 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.
• Each non-FILLER data-name must have a unique identifier within identifier-2.

Example 1

For example, consider the following data declaration:

 01 STRUCT. 
   02 STAT PIC X(4). 
   02 IN-AREA PIC X(100). 
   02 OK-AREA REDEFINES IN-AREA. 
     03 FLAGS PIC X. 
     03 PIC X(3). 
     03 COUNTER USAGE COMP-5 PIC S9(9). 
     03 ASFNPTR REDEFINES COUNTER USAGE FUNCTION-POINTER. 
     03 UNREFERENCED PIC X(92). 
   02 NG-AREA1 REDEFINES IN-AREA. 
     03 FLAGS PIC X.      03 PIC X(3). 
     03 PTR USAGE POINTER.
     03 ASNUM REDEFINES PTR USAGE COMP-5 PIC S9(9). 
     03 PIC X(92). 
   02 NG-AREA2 REDEFINES IN-AREA. 
     03 FN-CODE PIC X. 
     03 UNREFERENCED PIC X(3). 
     03 QTYONHAND USAGE BINARY PIC 9(5). 
     03 DESC USAGE NATIONAL PIC N(40). 
     03 UNREFERENCED PIC X(12).

The following data items from the example can be specified as identifier-2:

• STRUCT, of which subordinate data items STAT and IN-AREA would be converted to JSON format. (OK-AREA, NG-AREA1, and NG-AREA2 are ignored because they specify the REDEFINES clause.)
• OK-AREA, of which subordinate data items FLAGS, COUNTER, and UNREFERENCED would be converted. (The item whose data description entry specifies 03 PIC X(3) is ignored because it is an elementary FILLER data item. ASFNPTR is ignored because it specifies the REDEFINES clause.)
• Any of the elementary data items that are subordinate to STRUCT except:
  • ASFNPTR or PTR (disallowed usage)
  • UNREFERENCED OF NG-AREA2 (nonunique names for data items that are otherwise eligible)
  • Any FILLER data items

The following data items cannot be specified as identifier-2:

• NG-AREA1, because subordinate data item PTR specifies USAGE POINTER but does not specify the REDEFINES clause. (PTR would be ignored if it is defined with the REDEFINES clause.)
• NG-AREA2, because subordinate elementary data items have the nonunique name UNREFERENCED.

Example 2

The following example shows the UTF-8 and dynamic-length support for JSON GENERATE:

01 GRP.
   05 Ac-No PIC AA9999 value 'SX1234'.
   05 MORE.
      10 Stuff PIC S99V9 OCCURS 2.
   05 SSN PIC 999/99/9999 value SPACE.
01 d pic u dynamic limit 250.
   MOVE 7.8 TO stuff(1), MOVE -9 TO stuff(2)
   JSON GENERATE d FROM grp COUNT i

The output of the JSON GENERATE statement would be the UTF-8 encoded text in d containing the following JSON text:

{"GRP":{"Ac-No":"SX1234","MORE":{"Stuff":[7.8,-9.0]},"SSN":" "}}

COUNT phrase

If the COUNT phrase is specified, identifier-3 contains (after successful execution of the JSON GENERATE statement) the count of generated JSON character code points. If identifier-1 (the receiver) is of category national, the count is in double-bytes. If identifier-1 is of category UTF-8, the count is in Unicode code points. Otherwise, the count is in bytes.

identifier-3

The data count field. 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.

INDICATING phrase

The INDICATING phrase is specified with an indicated item, identifier-9, and an indicator item. The indicator item is specified either directly via identifier-10, or indirectly as the parent elementary item of condition-name-2.

The INDICATING phrase allows you to generate JSON null values for the indicated item when the indicator item contains the values specified in condition-name-2 or literal-3. In other words, the indicator item is a satellite data item that informs the JSON GENERATE statement if a JSON null value shall be generated.

Both the indicator item and the indicated item must be subordinate to identifier-2.

The indicator item must be a single byte alphanumeric elementary data item whose data definition entry contains PICTURE X.

condition-name-2 and literal-3 represent values of the indicator item. When the indicator item contains one of those values, the indicated item (in identifier-9) will be generated as a JSON null value. All other values of the indicator item will result in the indicated item being generated into JSON according to Operation of JSON GENERATE. The indicator item is otherwise ignored by the JSON GENERATE statement because the indicator item is not subject to conversion to JSON text.

condition-name-2 must be a level-88 item and can be specified with multiple values or value ranges. literal-2 must be a single byte alphanumeric literal.

The INDICATING phrase can be specified multiple times by using the ALSO keyword.

Below are three examples of the INDICATING phrase:

• Example 1:

    01 DOCX PIC X(1000).
    01 MY-RECORD.
      02 DATA-1-IS-NULL PIC X.
      02 DATA-1 PIC X(100).
  
    MOVE 'Y' TO DATA-1-IS-NULL
    JSON GENERATE DOCX FROM MY-RECORD
      INDICATING DATA-1 IS JSON NULL USING 'Y' IN DATA-1-IS-NULL
    END-JSON

  The output in docx encoded in UTF-8 is as follows:

  { "MY-RECORD" : { "DATA-1" : null } }

• Example 2:

    01 DOCX PIC X(1000).
    01 MY-RECORD.
      02 GRP OCCURS 2.
        03 DATA-1-IS-NULL PIC X.
        03 DATA-1 PIC X(100).
    MOVE 'VAL1' to DATA-1(1)
    MOVE 'VAL2' to DATA-1(2)
    MOVE 'Y' TO DATA-1-IS-NULL(1)
    MOVE 'N' TO DATA-1-IS-NULL(2)
    JSON GENERATE DOCX FROM MY-RECORD
      INDICATING DATA-1 IS JSON NULL USING 'Y' IN DATA-1-IS-NULL
    END-JSON

  The output in docx encoded in UTF-8 is as follows:

  {"MY-RECORD":{"GRP":[{"DATA-1":null},{"DATA-1":"VAL2"}]}}

• Example 3:

    01 DOCX PIC X(1000).
    01 MY-RECORD.
      02 GRP.
        03 DATA-1-IS-NULL PIC X OCCURS 2.
        03 DATA-1 PIC X(100) OCCURS 2.
    MOVE 'VAL1' to DATA-1(1)
    MOVE 'VAL2' to DATA-1(2)
    MOVE 'Y' TO DATA-1-IS-NULL(1)
    MOVE 'N' TO DATA-1-IS-NULL(2)
    JSON GENERATE DOCX FROM MY-RECORD
      INDICATING DATA-1 IS JSON NULL USING 'Y' IN DATA-1-IS-NULL
    END-JSON

  The output in docx encoded in UTF-8 is as follows:

  {"MY-RECORD":{"GRP":{"DATA-1":[null,"VAL2"]}}}

For a summary of the ways to generate JSON null values, see Generating JSON null values.

ENCODING phrase

The ENCODING phrase, if specified, determines the encoding of the generated JSON document. The ENCODING phrase must follow these rules:

• identifier-6 must be an unsigned integer data item.
• literal-3 must be an unsigned integer literal.
• If identifier-1 is alphanumeric:
  • The value of identifier-6 or literal-3 can be either an EBCDIC coded character set identifier (CCSID) from the below Table 1. "Single byte EBCDIC coded character sets for JSON documents" or 1208.
  • If FROM CODEPAGE was specified, the CCSID of the CODEPAGE compiler option is assumed and must be an EBCDIC CCSID from the below Table 1. "Single byte EBCDIC coded character sets for JSON documents".
• If identifier-1 is national or UTF-8:
  • The value of identifier-6 or literal-3 must be 1200 or 1208 respectively.
  • FROM CODEPAGE cannot be specified.

If the ENCODING phrase is omitted and:

• If identifier-1 is alphanumeric or UTF-8, the JSON document is encoded in Unicode UTF-8 (CCSID 1208).
• If identifier-1 is national, the JSON document is encoded in Unicode UTF-16 (CCSID 1200).

Table 1. Single byte EBCDIC coded character sets for JSON documents

CCSID	Description
1047	Latin 1/Open Systems
1140, 37	USA, Canada,…Euro Country Extended Code Page (ECECP), Country Extended Code Page (CECP)
1141, 273	Austria, Germany ECECP, CECP
1142, 277	Denmark, Norway ECECP, CECP
1143, 278	Finland, Sweden ECECP, CECP
1144, 280	Italy ECECP, CECP
1145, 284	Spain, Latin America (Spanish) ECECP, CECP
1146, 285	UK ECECP, CECP
1147, 297	France ECECP, CECP
1148, 500	International ECECP, CECP
1149, 871	Iceland ECECP, CECP

If the ENCODING phrase specifies a single byte EBCDIC CCSID, literal-1 of the JSON GENERATE NAME phrase must be an alphanumeric literal.

NAME phrase

Allows you to override the default JSON names derived from identifier-2 or its subordinate data items.

identifier-4 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 GENERATE statement. For more information about identifier-2, see the description of identifier-2. If identifier-4 is specified more than once in the NAME phrase, the last specification is used.

literal-1 must be an alphanumeric or national literal containing the name to be generated in the JSON text corresponding to identifier-4. With PTF for APAR PH18641 installed, alternatively, you can specify OMITTED to generate an anonymous JSON object or array, whose top-level parent name is not generated. For examples of generating JSON anonymous arrays, see Generating JSON anonymous arrays. With PTF for APAR PH58384 installed, OMITTED can be also used to generate only a JSON value (string, number, true, false, or null), whose JSON name is not generated in JSON name/value pairs.

When you specify OMITTED, identifier-4 must reference identifier-2.

If literal-1 is a NATIONAL or UTF-8 literal, identifier-1 must reference a data item of category NATIONAL or UTF-8, or the ENCODING phrase must specify a CCSID of 1208 for Unicode UTF-8.

SUPPRESS phrase

Allows you to identify and exclude items that are subordinate to identifier-2, and thus selectively generate output for the JSON GENERATE statement. If the SUPPRESS phrase is specified, identifier-1 must be large enough to contain the generated JSON document before any suppression.

With the generic-suppression-phrase, elementary items subordinate to identifier-2 that are not otherwise ignored by JSON GENERATE operations are identified generically for potential suppression. Either items of class numeric, if the NUMERIC keyword is specified, or items that are not of class numeric, if the NONNUMERIC keyword is specified, or both if neither is specified, might be suppressed.

If multiple generic-suppression-phrase are specified, the effect is cumulative.

If the generic-suppression-phrase is specified, data items are selected for potential suppression according to the following rules:

• 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.

identifier-5 explicitly identifies items for potential suppression. 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-5 cannot be a function identifier and cannot be reference modified or subscripted. If the WHEN phrase is specified, identifier-5 must reference an elementary data item. If the WHEN phrase is omitted, identifier-5 may be a group item. If identifier-5 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-5 are permitted.

If identifier-5 is specified, the following rules apply to it:

• If ZERO, ZEROES, or ZEROS is specified in the WHEN phrase, identifier-5 must not be of USAGE DISPLAY-1.
• If SPACE or SPACES is specified in the WHEN phrase, identifier-5 must be of USAGE DISPLAY, DISPLAY-1, or NATIONAL. If identifier-5 is a zoned or national decimal item, it must be an integer.
• If LOW-VALUE, LOW-VALUES, HIGH-VALUE, or HIGH-VALUES is specified in the WHEN phrase, identifier-5 must be of USAGE DISPLAY or NATIONAL. If identifier-5 is a zoned or national decimal item, it must be an integer.

The comparison operation that determines whether an item will be suppressed is a relation condition as shown in the table of Comparisons involving figurative constants. That is, the comparison is a numeric comparison if the value specified is ZERO, ZEROS, or ZEROES, and the item is of class numeric. For all other cases, the comparison operation is an alphanumeric, DBCS, national, or UTF-8 comparison, depending on whether the item is of usage DISPLAY, DISPLAY-1, NATIONAL, or UTF-8, respectively.

When the SUPPRESS phrase is specified, a group item subordinate to identifier-2 is excluded from the generated JSON text if all the eligible items subordinate to the group item are excluded. The outermost object that corresponds to identifier-2 itself is always generated, even if all the items subordinate to identifier-2 are excluded. In this case, the value generated for identifier-2 is an empty object, as follows:

{"identifier-2":{}}

For example, consider the following data declaration:

1 a.
 2 b.
  3 c occurs 0 to 2 depending j.
   4 d pic x.
 2 e pic x. 

If the ODO object j contains the value 2 and group a is populated with all ‘_’, the statement JSON GENERATE x FROM a (without the SUPPRESS phrase) produces the following JSON text:

{"a":{"b":{"c":[{"d":"_"},{"d":"_"}]},"e":"_"}}

Group item b is eliminated from the output if a SUPPRESS phrase specifies any one of data items b, c or d, resulting in the following JSON text:

{"a":{"e":"_"}}

As an example of complete recursive suppression, the statement JSON GENERATE x FROM a SUPPRESS b e produces:

{"a":{}}

JSON has an explicit representation of a table with no elements:

{"table-name":[]}

which is thus retained in the generated JSON text unless explicitly suppressed.

For example if ODO object j contains the value 0 and thus table d has no occurrences, and group a is populated with all '_', the statement JSON GENERATE x FROM a produces the following JSON text:

{"a":{"b":{"c":[]},"e":"_"}} 

Components of a zero-occurrence group table do not contribute any JSON text to the output. As a result, a SUPPRESS phrase that specified only d would have no effect on this generated output.

Suppressing data items b or c, and e, which do contribute JSON text, has the same result as for non-zero occurrences of table c, illustrated above.

CONVERTING phrase

Allows you to specify items that will be generated as either JSON BOOLEAN or JSON null name/value pairs.

converting-phrase Format 1

Use Format 1 to specify items that will be generated as JSON boolean name/value pairs.

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

condition-name-1 and literal-2 represent values of identifier-7 that will be generated as a JSON BOOLEAN true value. All other values of identifier-7 will be generated as a JSON BOOLEAN false value. condition-name-1 must be a level-88 item directly subordinate to identifier-7 and can be specified with multiple values or value ranges. literal-2 must be a single-byte alphanumeric literal.

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

For example, consider the following COBOL structure and statements:

01 myrecord.
  02 data-a PIC X.
  02 data-b PIC X.
    88 data-b-flag VALUE ‘a’ THRU ‘z’.

MOVE ‘F’ TO data-a
MOVE ‘b’ TO data-b

JSON GENERATE docx FROM myrecord
  CONVERTING data-a TO BOOLEAN USING ‘T’
        ALSO data-b TO BOOLEAN USING data-b-flag

The output of the JSON GENERATE statement would be the UTF-8 encoded text in docx containing the following JSON text:

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

converting-phrase Format 2

Use Format 2 to specify items that might be generated as JSON null name/value pairs.

identifier-8 must be a group or elementary item that references identifier-2 or is subordinate to identifier-2.

fig-con-1 represents one of the figurative constants from the list below:

• SPACE, SPACES
• ZERO, ZEROES, ZEROS
• LOW-VALUE, LOW-VALUES
• HIGH-VALUE, HIGH-VALUES

During execution of the JSON GENERATE statement, fig-con-1 will be compared to identifier-8 in an IS EQUAL relation condition. If the result of the comparison is true, the value of identifier-8 will be JSON null. Otherwise the value of identifier-8 will be generated as per the general rules of JSON GENERATE. fig-con-1 must be a permissible pair for comparison according to Table 3. "Comparisons involving figurative constants".

The following example shows a COBOL structure and statements generating JSON null values using the CONVERTING phrase:

01 docx pic x(100).
01 my-record.
 02 data-a pic 9999.
 02 data-b pic x(10).

MOVE zero TO data-a
MOVE low-values TO data-b

JSON GENERATE docx FROM my-record
  CONVERTING data-a TO NULL USING zero
        ALSO data-b TO NULL USING low-values
END-JSON

The output of the JSON GENERATE statement would be the UTF-8 encoded text in docx containing the following JSON text:

{ "myrecord" : { "data-a" : null, "data-b" : null } }

Note: identifier-7 of Format 1 and identifier-8 might reference the same data item, which might be useful when you want to convert the item to JSON true, false, or null.

ON EXCEPTION phrase

An exception condition exists when an error occurs during generation of the JSON document, for example if identifier-1 is not large enough to contain the generated JSON document. In this case, JSON generation stops and the content of the receiver, identifier-1, is undefined. If the COUNT phrase is specified, identifier-3 contains the number of character positions that were actually generated.

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 GENERATE statement. Special register JSON-CODE contains an exception code, as detailed in JSON GENERATE exceptions in the Enterprise COBOL Programming Guide.

NOT ON EXCEPTION phrase

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

END-JSON phrase

This explicit scope terminator delimits the scope of the 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.