JSON GENERATE statement
The JSON GENERATE statement converts data to JSON format.
You can watch this video to get an overview of the JSON support in Enterprise COBOL V6.
- 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
When identifier-1 references a national group item, identifier-1 is processed as an elementary data item of category national. 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 or identifier-3.
The generated JSON text is encoded in UTF-8 (CCSID 1208) unless identifier-1 is of category national, in which case it is encoded in UTF-16 big-Endian (CCSID 1200). Conversion of the data values and NAME phrase literals is done according to the compiler CODEPAGE option in effect for the compilation. Conversion of original data names is always done using CCSID 1140.
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 cannot be a function identifier or be reference modified, but it can be subscripted.
identifier-2 must not overlap identifier-1 or identifier-3.
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.
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 itemsSTAT
andIN-AREA
would be converted to JSON format. (OK-AREA
,NG-AREA1
, andNG-AREA2
are ignored because they specify the REDEFINES clause.)OK-AREA
, of which subordinate data itemsFLAGS
,COUNTER
, andUNREFERENCED
would be converted. (The item whose data description entry specifies03 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
orPTR
(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 itemPTR
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 nameUNREFERENCED
.
- 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 encoding units. If identifier-1 (the
receiver) is of category national, the count is in double-bytes. 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.
- NAME phrase
- Allows you to override the default JSON names derived from identifier-2 or its subordinate data items.
- 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.
- CONVERTING phrase
-
Allows you to specify items that will be generated as JSON BOOLEAN name/value pairs.
identifier-6 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-6 that will be generated as a JSON BOOLEAN true value. All other values of identifier-6 will be generated as a JSON BOOLEAN false value. 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.
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
The output of the JSON GENERATE statement would be the UTF-8 encoded text in docx containing:JSON GENERATE docx FROM myrecord CONVERTING data-a TO BOOLEAN USING ‘T’ ALSO data-b TO BOOLEAN USING data-b-flag
{ “myrecord” : { “data-a” : false, “data-b” : true } }
- 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.