The daily edition.

Scope and Architectural Overview

This article covers native JSON serialization and deserialization in Rocket Enterprise Developer / Enterprise Server 12.0 for Linux/UNIX.

Modernizing COBOL applications often requires exchanging payloads directly with RESTful web APIs and microservices. Rather than requiring external string parsers, C wrappers, or intermediate files, Rocket COBOL implements native language syntax through the The JSON GENERATE Statement and The JSON PARSE Statement.

These statements convert between hierarchical COBOL group/elementary records and structured JSON documents, enforcing strict data typing, character encodings (UTF-8, UTF-16, or EBCDIC), and special register status tracking.

JSON GENERATE: Transformation, OMITTED Objects, and Null Mapping

The JSON GENERATE statement converts COBOL data items (identifier-2) into a JSON formatted character string (identifier-1).

JSON GENERATE json-doc FROM customer-record
     COUNT IN char-count
     NAME OF cust-id IS "customerId"
     SUPPRESS customer-notes WHEN SPACES
     ON EXCEPTION
         PERFORM handle-json-error
     NOT ON EXCEPTION
         PERFORM process-json-success
END-JSON

Key operational mechanics include:

1. Receiver Sizing Constraint: identifier-1 must be large enough to contain the generated JSON text including property names, quotes, colons, and braces. Rocket documentation advises sizing the receiving buffer 2 to 3 times the size of the source data item. If the receiver buffer is too small, generation fails with exception code 1 in JSON-CODE.
2. Filtering Subordinate Fields: Unnamed elementary items, FILLER fields, slack bytes inserted for SYNCHRONIZED items, pointer types, and items defined with REDEFINES or RENAMES are automatically ignored during generation.
3. Prefix Stripping: If a COBOL data-name begins with a # character, the # is automatically stripped from the generated JSON property name.
4. Anonymous Objects via OMITTED: Using NAME OF identifier-2 IS OMITTED generates an anonymous JSON object without an outer top-level wrapper object. Similarly, applying OMITTED (or the Rocket ALL keyword) to a table generates an anonymous JSON array.
5. Null and Boolean Mapping: As illustrated in JSON GENERATE Examples, the CONVERTING phrase converts level-88 conditional flags to JSON true/false booleans, or maps figurative constants (such as SPACES or ZEROES) to JSON null. Alternatively, the INDICATING phrase evaluates an external single-byte indicator field (or level-88 condition) to emit JSON null.

JSON PARSE: Ingestion, Matching Rules, and Null Suppression

The JSON PARSE statement populates a COBOL target record (identifier-2) by matching name/value pairs from a JSON source string (identifier-1):

JSON PARSE json-doc INTO customer-record
     WITH DETAIL
     IGNORING ALL
     ON EXCEPTION
         DISPLAY "Parse failed with code: " JSON-CODE
END-JSON

Key ingestion rules include:

1. Name Matching Algorithm: Property names in the JSON document are matched to COBOL identifiers. Whitespace outside string literals is ignored.
2. The IGNORING and INDICATING Phrases: By default, encountering a JSON null value raises warning status 32 in the JSON-STATUS special register. Specifying IGNORING ALL suppresses this behavior and bypasses unhandled null fields. Alternatively, INDICATING moves indicator flags into specific PIC X variables to track which input attributes contained nulls.
3. Partial Modification Risk: If a syntax error or schema mismatch occurs midway through parsing, the statement terminates immediately, but fields parsed prior to the failure point remain populated in identifier-2. Applications must always verify success before consuming parsed records.

Exception Codes and Special Registers

Execution outcomes are communicated through two dedicated special registers detailed in JSON-CODE Exception Codes:

• JSON-CODE:
  • 0: Execution completed successfully.
  • 1: (JSON GENERATE) The receiving field was too small for the generated text. If COUNT IN was specified, it contains the character count actually generated before overflow.
  • 100: (JSON PARSE) Invalid JSON syntax at specified line and character offset.
  • 101: (JSON PARSE) JSON input was empty or consisted entirely of whitespace.
  • 104: (JSON PARSE) JSON value was incompatible with the matching COBOL elementary data item.
  • 105: (JSON PARSE) Unexpected JSON true or false boolean value encountered without a corresponding CONVERTING phrase.
  • 106: (JSON PARSE) No JSON property names matched any target COBOL data item.
• JSON-STATUS: Captures non-exception warning conditions during parsing, such as status code 32 when unhandled null values are encountered.

Operational Prerequisites and Nuances

• Dynamic-Length Data Item Prohibition: Neither the JSON source/receiver text nor the COBOL record structure can be defined as a dynamic-length group or dynamic-length elementary item.
• OCCURS DEPENDING ON (ODO) Interaction: If target structures use ODO tables, the controlling ODO object variable must not reside within the target record itself; JSON PARSE does not update the ODO object field during array ingestion.
• Encoding Precedence: JSON text is assumed to be UTF-8 (CCSID 1208). If the data item is category NATIONAL, UTF-16 (CCSID 1200) is used. When parsing EBCDIC strings, the ENCODING phrase must specify an EBCDIC CCSID or FROM CODEPAGE, which aligns with the active MFCODESET environment variable.

Documentation Takeaway

In Rocket Enterprise Developer 12.0 for Linux/UNIX, JSON GENERATE and JSON PARSE eliminate external parsing libraries by transforming between COBOL structures and JSON text directly; developers must allocate receiving buffers at 2–3 times record size to prevent JSON-CODE 1 truncations, handle nulls and booleans explicitly via CONVERTING and INDICATING, and inspect JSON-CODE before trusting partially populated records on exception.